# Quickstart

> Connect a coding agent to SuperDoc through MCP and produce a reviewable tracked edit.



The MCP server lets a coding agent open, read, edit, and save `.docx` files on your machine. It is the fastest way to see agent-driven document editing, because the agent you already use supplies the model loop.

This quickstart connects the server, inspects a document, proposes a tracked edit, and saves the result to a separate file you can review.

## 1. Connect the server [#1-connect-the-server]

The server runs locally over stdio. Your MCP client spawns it as a subprocess, so you never start it yourself.

For Claude Code:

```bash
claude mcp add superdoc -- pnpm dlx @superdoc-dev/mcp
```

For Claude Desktop, Cursor, or Windsurf, add the same command to the client's MCP configuration file:

```json
{
  "mcpServers": {
    "superdoc": {
      "command": "pnpm",
      "args": ["dlx", "@superdoc-dev/mcp"]
    }
  }
}
```

Claude Desktop reads `~/Library/Application Support/Claude/claude_desktop_config.json`. Cursor reads `~/.cursor/mcp.json`. Windsurf reads `~/.codeium/windsurf/mcp_config.json`. Restart the client after editing the file.

> **The agent gets filesystem reach (warning)**
>
> The server reads and writes any path the agent supplies, with no restriction to a particular directory. Point it at
> copies, and see [Safety](/agents/operate/safety) for how to contain it properly.


## 2. Prepare a document [#2-prepare-a-document]

Download the synthetic NDA and save it as `contract.docx`. It contains the word `termination` and one existing tracked change.

[Download the tracked-changes fixture](/fixtures/tracked-changes.docx): Synthetic NDA with one tracked change · DOCX


Note its absolute path, for example `/Users/you/documents/contract.docx`. The prompts below use it.

> **Use absolute paths (warning)**
>
> A relative path resolves against the server process's working directory, which a GUI client like Claude Desktop sets
> somewhere you did not choose. `superdoc_open` also opens a blank document when the path does not exist instead of
> reporting an error, so a wrong path looks like an empty file rather than a mistake.


## 3. Inspect before editing [#3-inspect-before-editing]

Ask the agent to read the document first, using the absolute path:

```text
Open /Users/you/documents/contract.docx with SuperDoc and summarize the
termination clause.
```

The agent calls `superdoc_open`, which returns a `session_id` that every later call reuses, then reads content through `superdoc_get_content`. Reading first matters: an agent that edits before inspecting is guessing at what the document contains.

If the summary comes back empty or describes a document with no termination clause, the path was wrong and the agent is looking at a blank file.

## 4. Propose a tracked edit [#4-propose-a-tracked-edit]

Ask for a change that a person should approve:

```text
Rewrite the termination clause to allow 30-day notice. Make it a tracked change
and save to /Users/you/documents/contract.reviewed.docx so the original stays
untouched.
```

Tracked mode records the edit as a suggestion rather than overwriting text, and the separate output path keeps your source file intact. Both instructions are worth making explicit: the agent will otherwise apply a direct edit and save over the original.

> **Saving overwrites without asking (warning)**
>
> `superdoc_save` has no overwrite guard. Whatever path the agent passes gets written, replacing any file already there.
> Name an output that does not exist yet, and keep the source somewhere the agent is not writing.


## 5. Verify the output [#5-verify-the-output]

Open `contract.reviewed.docx` in the editor below, or in Microsoft Word. The rewrite should appear as a tracked change you can accept or reject, and `contract.docx` should be unchanged.

> **Interactive editor: Review the agent output**
>
> Sample: [open the fixture](/fixtures/tracked-changes.docx).
> Preset: `tracked-review`.
> Tracked-change review: accept or reject the sample change.
> Local DOCX selection: enabled. Files remain in the browser.


> **Verification target (success)**
>
> The output contains the rewritten clause as a pending tracked change. The source file is byte-for-byte unchanged.


## What the server exposes [#what-the-server-exposes]

The tool count depends on the preset. Three lifecycle tools are always present; the editing surface comes from the preset.

| `MCP_PRESET`       | Tools                                                             |
| ------------------ | ----------------------------------------------------------------- |
| `legacy` (default) | 13: 3 lifecycle + 10 grouped intent tools                         |
| `core`             | 5: 3 lifecycle + `superdoc_inspect` and `superdoc_perform_action` |

This guide uses the server default so the setup above works with no extra configuration. That default is `legacy`, which is why this page shows those tools while [Build an agent](/agents/build/build-an-agent) recommends `core` for SDK integrations. To run the core surface here too, add the environment variable to your client config:

```json
{
  "mcpServers": {
    "superdoc": {
      "command": "pnpm",
      "args": ["dlx", "@superdoc-dev/mcp"],
      "env": { "MCP_PRESET": "core" }
    }
  }
}
```

The lifecycle tools are identical either way:

| Tool             | Purpose                                                             |
| ---------------- | ------------------------------------------------------------------- |
| `superdoc_open`  | Open a `.docx` file and return a `session_id`                       |
| `superdoc_save`  | Write to the original path, or to `out`. Overwrites without warning |
| `superdoc_close` | Close the session and release memory                                |

The default `legacy` preset adds ten grouped intent tools:

| Tool                                         | Purpose                                  |
| -------------------------------------------- | ---------------------------------------- |
| `superdoc_get_content`, `superdoc_search`    | Read content and find stable targets     |
| `superdoc_edit`, `superdoc_format`           | Change text and apply formatting         |
| `superdoc_create`, `superdoc_list`           | Add blocks and manipulate lists          |
| `superdoc_table`                             | Build and change tables                  |
| `superdoc_comment`, `superdoc_track_changes` | Manage comments and resolve suggestions  |
| `superdoc_mutations`                         | Run multi-step edits as one atomic batch |

Every tool except `superdoc_open` takes the `session_id`. Unsaved work is lost on close, so the agent must save before closing.

## Where to go next [#where-to-go-next]

Building the agent yourself, rather than connecting an existing one, means embedding the tool loop in your product. [Build an agent](/agents/build/build-an-agent) covers that path with the SDK toolkit.

Before putting an agent near documents that matter, read [Safety](/agents/operate/safety).