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

# Connect Anvil MCP Server to Claude Desktop — Guide

> Use anvil mcp --stdio to connect your Anvil tools to Claude Desktop with a single config snippet — no separate server process required.

Claude Desktop discovers MCP servers through a local config file and communicates with them over stdin/stdout. Anvil's `--stdio` flag switches the MCP server from Streamable HTTP to the newline-delimited JSON-RPC transport that Claude Desktop (and other local clients) expect.

## Transport modes

Anvil supports two MCP transport modes. Choose the one that fits your client:

<Tabs>
  <Tab title="Streamable HTTP (default)">
    The default mode starts an HTTP server that accepts `POST` requests at `/mcp`. Use this for remote agents, AI frameworks (Vercel AI SDK, LangChain, etc.), or any client that speaks HTTP.

    ```bash theme={null}
    anvil mcp
    # [anvil] mcp (Streamable HTTP) on http://localhost:3100/mcp
    # [anvil] 2 tool(s): get_users_by_id, wordCount
    ```

    Point your agent or framework at `http://localhost:3100/mcp` (or the host/port you configure with `--port` and `--endpoint`).
  </Tab>

  <Tab title="stdio (Claude Desktop)">
    The `--stdio` flag switches to the stdio transport. Anvil reads JSON-RPC requests from stdin and writes responses to stdout, one message per line. Claude Desktop (and other local clients) spawn `anvil mcp --stdio` as a child process and communicate over its standard streams.

    ```bash theme={null}
    anvil mcp --stdio
    # Diagnostics go to stderr — stdout is reserved for the protocol.
    ```

    <Note>
      In stdio mode, all diagnostic output (tool counts, startup messages, errors) goes to **stderr**. Never write to stdout in your tool handlers — stdout is the protocol channel and corrupting it will break the JSON-RPC framing.
    </Note>
  </Tab>
</Tabs>

## Configure Claude Desktop

To add your Anvil project as an MCP server in Claude Desktop, edit the `claude_desktop_config.json` file and add an entry under `mcpServers`:

```json theme={null}
{
  "mcpServers": {
    "anvil": {
      "command": "npx",
      "args": ["anvil", "mcp", "--stdio"],
      "cwd": "/path/to/your/project"
    }
  }
}
```

Replace `/path/to/your/project` with the absolute path to the directory that contains your `server/` folder. Claude Desktop will spawn `npx anvil mcp --stdio` in that directory whenever it needs to call one of your tools.

<Note>
  **Where to find `claude_desktop_config.json`:**

  * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
  * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

  Create the file if it doesn't exist yet. After saving, restart Claude Desktop for the changes to take effect.
</Note>

## Step-by-step setup

<Steps>
  <Step title="Annotate at least one route or add a standalone tool">
    Make sure you have at least one MCP-exposed route (`meta.mcp.expose = true`) or a file in `server/tools/`. Without any tools, the server starts but Claude Desktop has nothing to call.

    ```ts theme={null}
    // server/routes/users/[id]/get.ts
    export const meta = { mcp: { expose: true, description: 'Fetch a user by ID' } };
    export const paramsSchema = z.object({ id: z.string() });
    export default (ctx) => findUser(ctx.params.id);
    ```
  </Step>

  <Step title="Verify with a local test">
    Confirm the server starts cleanly before touching the Claude Desktop config:

    ```bash theme={null}
    npx anvil mcp --stdio
    ```

    You should see a line on stderr listing your tools. If there are any schema errors, fix them before proceeding.
  </Step>

  <Step title="Edit claude_desktop_config.json">
    Open the config file for your OS (see the note above) and add the `anvil` server entry:

    ```json theme={null}
    {
      "mcpServers": {
        "anvil": {
          "command": "npx",
          "args": ["anvil", "mcp", "--stdio"],
          "cwd": "/absolute/path/to/your/project"
        }
      }
    }
    ```
  </Step>

  <Step title="Restart Claude Desktop">
    Quit and reopen Claude Desktop. Open a new conversation — your Anvil tools should now appear in the tool list. Ask Claude to call one of them to confirm the connection.
  </Step>
</Steps>

## Using a local binary instead of npx

If you have `anvil` installed globally or in your project's `.bin/`, reference it directly to avoid the `npx` startup overhead:

```json theme={null}
{
  "mcpServers": {
    "anvil": {
      "command": "/absolute/path/to/your/project/node_modules/.bin/anvil",
      "args": ["mcp", "--stdio"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}
```

## Connecting other MCP-compatible clients

The Streamable HTTP mode (`anvil mcp` without `--stdio`) works with any client or framework that implements the MCP spec over HTTP:

| Client / Framework       | Connect to                       |
| ------------------------ | -------------------------------- |
| Vercel AI SDK            | `http://localhost:3100/mcp`      |
| LangChain / LangGraph    | `http://localhost:3100/mcp`      |
| Custom JSON-RPC client   | `POST http://localhost:3100/mcp` |
| Any MCP-compatible agent | `http://localhost:3100/mcp`      |

Change the default port or endpoint path with `--port` and `--endpoint`:

```bash theme={null}
anvil mcp --port 4000 --endpoint /tools
# [anvil] mcp (Streamable HTTP) on http://localhost:4000/tools
```

<Tip>
  Run `anvil lint` before connecting Claude Desktop to make sure every exposed route's schema converts cleanly. Lint catches issues at build time rather than surfacing them as confusing runtime errors inside Claude.
</Tip>