# superdoc_create

IMPORTANT: For headings and paragraphs, use superdoc_edit with type "markdown" instead: it is faster, creates proper styles, and handles positioning via target + placement. Only use superdoc_create for tables or when markdown cannot express the content. Creates a single paragraph, heading, or table. Returns nodeId, an opaque handle.ref for the created block, and evaluatedRevision. handle.ref works directly with superdoc_format (pass expectedRevision as evaluatedRevision to avoid REVISION_MISMATCH) and already carries its story, including for a header/footer block — no need to pass story separately. It is valid for ONE immediate follow-up call only; for anything after that, re-fetch blocks with superdoc_get_content to get a fresh ref. If "text" is empty, handle.ref spans no characters and cannot be used with superdoc_format action "inline" (it needs at least one character); use a block target with nodeId for paragraph-level actions like set_style or set_alignment instead. When the user asks for a "heading", use action "heading" with a level (default 1). Use action "paragraph" for regular body text. Position with "at": {kind:"documentEnd"} (default), {kind:"documentStart"}, or {kind:"after"/"before", target:{kind:"block", nodeType, nodeId}} for relative placement. When creating multiple items in sequence, use the previous response nodeId as the next "at" target to maintain correct ordering. Do NOT use newlines in "text" to create multiple paragraphs; call this tool separately for each one. EXAMPLES: 1. {"action":"paragraph","text":"New paragraph content.","at":{"kind":"documentEnd"}} 2. {"action":"heading","text":"Section Title","level":2,"at":{"kind":"after","target":{"kind":"block","nodeType":"paragraph","nodeId":"<nodeId>"}}} 3. {"action":"paragraph","text":"Chained item.","at":{"kind":"after","target":{"kind":"block","nodeType":"paragraph","nodeId":"<previousNodeId>"}}} 4. {"action":"table","rows":3,"columns":4,"at":{"kind":"documentEnd"}}

Agent View of the PolicyLayer registry record for `superdoc_create`. HTML page: https://policylayer.com/tools/superdoc-mcp/superdoc-create

## Facts

- Tool: `superdoc_create`
- Server: Superdoc (`@superdoc/mcp`) — https://policylayer.com/tools/superdoc-mcp.md
- Install: `npx -y @superdoc/mcp`
- Homepage: https://www.npmjs.com/package/@superdoc/mcp
- Risk category: Write (Medium risk)
- Registry record: grade F, identity unverified
- Server rate-limited: no
- Parameters: 12 (1 required)
- Recommended policy verdict: Rate-limited

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `at` | object | no | Position: {kind:'documentEnd'} to append, {kind:'documentStart'} to prepend, or {kind:'before'\|'after', target:{kind:'block', nodeType:'...', nodeId:'...'}} for |
| `in` | object | no | Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, e |
| `rows` | integer | no | Required for action 'table'. |
| `text` | object | no | Paragraph text content. Each call creates ONE paragraph. For multiple items (e.g. list items), call superdoc_create separately for each item: do NOT use newline |
| `force` | boolean | no | Bypass confirmation checks. |
| `input` | object | no | Full paragraph input as JSON (alternative to individual text/at params). |
| `level` | integer | no | Heading level (1-6). Required for action 'heading'. |
| `action` | string | yes | The action to perform. One of: heading, paragraph, table. |
| `dryRun` | boolean | no | Preview the result without applying changes. |
| `columns` | integer | no | Required for action 'table'. |
| `styleId` | object | no | Explicit paragraph style id (e.g. "BodyText") to apply instead of the default resolved from the anchor/document. An unknown style id fails with INVALID_INPUT an |
| `changeMode` | string | no | Edit mode: "direct" applies changes immediately, "tracked" records as suggestions. |

Parameters from the server's own tool schema.

## Example call (MCP tools/call, JSON-RPC 2.0)

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "superdoc_create",
    "arguments": {
      "action": "<action>"
    }
  }
}
```

## Why superdoc_create is rated Medium

An AI agent can call superdoc_create faster than any human can review: one bad instruction and it creates or modifies resources in Superdoc by the hundred, each call as confident as the last.

Risk signals: High parameter count (13 properties)

## Use case

AI agents use superdoc_create to create or update resources in Superdoc, usually the action step of a workflow, after the agent has gathered context. Every call changes real data in your Superdoc environment.

## Recommended policy (PolicyLayer)

Verdict: **Rate-limited**. Enforced by the PolicyLayer MCP gateway (https://policylayer.com/mcp-gateway) before a call reaches Superdoc:

```json
{
  "version": "1",
  "default": "deny",
  "tools": {
    "superdoc_create": {
      "limits": [
        {
          "counter": "superdoc_create_rate",
          "window": "minute",
          "max": 30,
          "scope": "grant"
        }
      ]
    }
  }
}
```

## Other tools on Superdoc (12)

- `superdoc_mutations` — Destructive — https://policylayer.com/tools/superdoc-mcp/superdoc-mutations.md
- `superdoc_table` — Destructive — https://policylayer.com/tools/superdoc-mcp/superdoc-table.md
- `superdoc_track_changes` — Destructive — https://policylayer.com/tools/superdoc-mcp/superdoc-track-changes.md
- `superdoc_format` — Execute — https://policylayer.com/tools/superdoc-mcp/superdoc-format.md
- `superdoc_get_content` — Read — https://policylayer.com/tools/superdoc-mcp/superdoc-get-content.md
- `superdoc_list` — Read — https://policylayer.com/tools/superdoc-mcp/superdoc-list.md
- `superdoc_search` — Read — https://policylayer.com/tools/superdoc-mcp/superdoc-search.md
- `superdoc_close` — Write — https://policylayer.com/tools/superdoc-mcp/superdoc-close.md
- `superdoc_comment` — Write — https://policylayer.com/tools/superdoc-mcp/superdoc-comment.md
- `superdoc_edit` — Write — https://policylayer.com/tools/superdoc-mcp/superdoc-edit.md
- `superdoc_open` — Write — https://policylayer.com/tools/superdoc-mcp/superdoc-open.md
- `superdoc_save` — Write — https://policylayer.com/tools/superdoc-mcp/superdoc-save.md

## For agents

This record is a snapshot. Live verdicts and the full registry:

- Check every server in your MCP config at once: `npx -y policylayer stack`
- Vet a server before you add it: install the mcp-precheck skill — `npx skills add https://policylayer.com` (skill text: https://policylayer.com/skill.md)
- Query the registry over MCP: endpoint `https://api.policylayer.com/mcp` — tools `check_mcp_server`, `check_mcp_stack`, `check_tool`, `search_registry`, `get_change_events`

---

Source: the PolicyLayer MCP registry — one continuously verified record per MCP server. Full record: https://policylayer.com/registry?q=superdoc-mcp · API: https://policylayer.com/registry/api · Policy library: https://policylayer.com/policies/superdoc-mcp