> ## 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.

# Anvil JS MCP: Expose Any Route as an AI Agent Tool

> Anvil's MCP layer exposes your routes and standalone tools to any AI agent or MCP client — one codebase, one handler, no duplicated schemas.

The Model Context Protocol (MCP) is an open standard that lets AI agents and clients like Claude discover and call tools over a well-defined interface. Anvil builds MCP support directly into the framework: the same route handler you write for your REST API can simultaneously be an agent-callable tool, with zero schema duplication.

## Why Anvil's approach is different

Most frameworks require you to maintain two parallel surfaces — an HTTP API and a separate tool definition — each with its own schema and validation logic. Anvil eliminates that split. When you mark a route with `meta.mcp.expose`, Anvil reads its `paramsSchema` (a Zod object you already defined for HTTP validation), converts it to JSON Schema automatically, and advertises the tool to MCP clients. The same handler function runs in both contexts.

```
┌─────────────────────────────────────────────────┐
│  server/routes/users/[id]/get.ts                │
│                                                 │
│  meta.mcp.expose = true  ──────────────────┐   │
│  paramsSchema = z.object({ id: z.string() })│   │
│  export default (ctx) => findUser(ctx.params.id) │
└─────────────────────────────────────────────────┘
         │                        │
         ▼                        ▼
  GET /users/:id          MCP tool: get_users_by_id
  (HTTP route)            (agent-callable)
```

Standalone tools that don't map to an HTTP route live in `server/tools/` and are served by the same command.

## How it works

<Steps>
  <Step title="Annotate a route (or add a standalone tool)">
    Add `meta.mcp.expose = true` and a `paramsSchema` to any route file, or drop a new file in `server/tools/` with a default function and an `inputSchema`.
  </Step>

  <Step title="Run anvil mcp">
    Start the MCP server with `anvil mcp`. By default it listens on `:3100/mcp` over Streamable HTTP. Pass `--stdio` for local clients like Claude Desktop.

    ```bash theme={null}
    anvil mcp              # Streamable HTTP → http://localhost:3100/mcp
    anvil mcp --stdio      # stdio transport for Claude Desktop
    ```
  </Step>

  <Step title="Tools appear in your agent or client">
    Any MCP-compatible client — Claude Desktop, a custom agent built with the Vercel AI SDK, LangChain, or your own JSON-RPC client — can now discover and call your tools. Anvil handles the `tools/list` and `tools/call` protocol methods.
  </Step>
</Steps>

## Transport modes

| Mode            | Command             | Endpoint                    | Best for                         |
| --------------- | ------------------- | --------------------------- | -------------------------------- |
| Streamable HTTP | `anvil mcp`         | `http://localhost:3100/mcp` | Remote agents, AI frameworks, CI |
| stdio           | `anvil mcp --stdio` | stdin/stdout                | Claude Desktop, local CLI tools  |

The default port and endpoint (`--port` / `--endpoint` flags) can be changed at the command line. See the [CLI reference](/cli/mcp) for all flags.

## What gets served

`anvil mcp` collects tools from two places and merges them into a single MCP server:

1. **Route-derived tools** — every route file that exports `meta.mcp.expose = true`
2. **Standalone tools** — every file in `server/tools/` that default-exports a function

Tool names must be globally unique. Collisions are caught at startup with a clear error pointing to both files.

<Note>
  `anvil lint` validates MCP-exposed routes at build time: it checks that `paramsSchema` keys match the folder params in the path and that the schema converts losslessly to JSON Schema. Run `anvil lint --strict` to treat schema-conversion warnings as errors.
</Note>

## Learn more

<CardGroup cols={3}>
  <Card title="Exposing Routes" icon="route" href="/mcp/exposing-routes">
    Mark a route with `meta.mcp.expose` and let Anvil generate the tool definition from your existing Zod schema.
  </Card>

  <Card title="Standalone Tools" icon="wrench" href="/mcp/standalone-tools">
    Define tools that aren't tied to an HTTP route in `server/tools/` and serve them from the same `anvil mcp` command.
  </Card>

  <Card title="Claude Desktop" icon="robot" href="/mcp/claude-desktop">
    Connect your Anvil MCP server to Claude Desktop in minutes using stdio mode and a one-line config snippet.
  </Card>
</CardGroup>