> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vespper.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Vespper to your AI assistant

> Connect Claude Code, Cursor, Codex, or another local MCP client to read and edit Word documents with Vespper.

Use `vespper-mcp` to give an existing AI assistant access to Word documents on
your computer. The package runs locally as a stdio MCP server, limits file
access to directories you allow, and communicates with Vespper MCP in the cloud
behind the scenes. Successful edits are saved back to the original `.docx`
file.

## Before you start

You need:

* Node.js 22 or newer
* A [Vespper API key](https://app.vespper.com/keys)
* An absolute path to a directory containing the documents your assistant can
  access

Set your API key in the environment that starts your assistant:

```bash theme={"system"}
export VESPPER_API_KEY="sk_live_YOUR_KEY"
```

## Connect your assistant

Replace `/absolute/path/to/documents` with the directory your assistant can
access. Use an absolute path because MCP clients start servers without shell
path expansion.

<Tabs sync={false}>
  <Tab title="Claude Code">
    Add `.mcp.json` to your project:

    ```json theme={"system"}
    {
      "mcpServers": {
        "vespper": {
          "command": "npx",
          "args": [
            "-y",
            "vespper-mcp",
            "--allowed-directory",
            "/absolute/path/to/documents"
          ],
          "env": {
            "VESPPER_API_KEY": "${VESPPER_API_KEY}"
          }
        }
      }
    }
    ```

    Claude Code asks you to approve project-scoped MCP servers before using
    them.
  </Tab>

  <Tab title="Cursor">
    Add `.cursor/mcp.json` to your project, or use `~/.cursor/mcp.json` to make
    the server available in every project:

    ```json theme={"system"}
    {
      "mcpServers": {
        "vespper": {
          "type": "stdio",
          "command": "npx",
          "args": [
            "-y",
            "vespper-mcp",
            "--allowed-directory",
            "/absolute/path/to/documents"
          ],
          "env": {
            "VESPPER_API_KEY": "${env:VESPPER_API_KEY}"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    Add the server to `~/.codex/config.toml`:

    ```toml theme={"system"}
    [mcp_servers.vespper]
    command = "npx"
    args = [
      "-y",
      "vespper-mcp",
      "--allowed-directory",
      "/absolute/path/to/documents",
    ]
    env_vars = ["VESPPER_API_KEY"]
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Open **Settings → Developer → Edit Config**, then add:

    ```json theme={"system"}
    {
      "mcpServers": {
        "vespper": {
          "command": "npx",
          "args": [
            "-y",
            "vespper-mcp",
            "--allowed-directory",
            "/absolute/path/to/documents"
          ],
          "env": {
            "VESPPER_API_KEY": "sk_live_YOUR_KEY"
          }
        }
      }
    }
    ```

    This configuration is stored locally. Do not commit or share a
    configuration containing your API key.
  </Tab>

  <Tab title="Other MCP clients">
    Clients that accept the common JSON stdio configuration can use:

    ```json theme={"system"}
    {
      "command": "npx",
      "args": [
        "-y",
        "vespper-mcp",
        "--allowed-directory",
        "/absolute/path/to/documents"
      ],
      "env": {
        "VESPPER_API_KEY": "sk_live_YOUR_KEY"
      }
    }
    ```

    Prefer your client's secret store or environment inheritance when it
    supports one.
  </Tab>
</Tabs>

Restart your assistant after changing its MCP configuration.

## Try an edit

Ask your assistant to open a document inside the allowed directory and describe
the change you want:

> Open `/absolute/path/to/documents/contract.docx`, change the payment term
> from 30 days to 45 days, and keep the edit as a tracked change.

The assistant can use five tools:

* `open_document` opens one or more local `.docx` files.
* `read_document` reads a page range as editable HTML.
* `search_document` finds text without loading the entire document.
* `edit_document` applies tracked edits and saves the updated file.
* `close_document` saves pending changes and closes the document session.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.