---
title: MCP Integration
description: Connect your actions to Claude Desktop, Cursor, and other MCP clients.
canonical_url: https://next-ai-ready.vercel.app/en/docs/guides/mcp-integration
url: https://next-ai-ready.vercel.app/en/docs/guides/mcp-integration
last_updated: 2026-08-01
updated: 2026-08-01
author: next-ai-ready team
summary: Connect your actions to Claude Desktop, Cursor, and other MCP clients.
topics: [how-to, best-practices]
---

# MCP Integration

The Model Context Protocol (MCP) lets AI clients like Claude Desktop and Cursor discover and call your actions as tools. `next-ai-ready` exposes an MCP server at `/api/mcp`.

## What MCP gives you

- **Tool discovery** — MCP clients see your public actions as callable tools.
- **Resource access** — your pages are exposed as MCP resources (Markdown content).
- **Page discovery** — clients can list, read, and search graph pages without knowing resource URIs in advance.
- **Two transports** — Streamable HTTP (production) and stdio (local desktop clients).

## HTTP endpoint (production)

After `next-ai-ready init`, the MCP server is available at `/api/mcp`. It handles Streamable HTTP, SSE, and session management via `vercel/mcp-handler`.

Connect any MCP-compatible client to `https://your-site.com/api/mcp`.

## Stdio (local clients)

For desktop clients like Claude Desktop, run the stdio server:

```bash
npx next-ai-ready mcp
```

This starts an MCP server over stdin/stdout. Add it to your Claude Desktop config:

```json
{
  "mcpServers": {
    "my-site": {
      "command": "npx",
      "args": ["next-ai-ready", "mcp"]
    }
  }
}
```

Use `--no-resources` to skip graph-backed page resources and discovery tools (faster startup):

```bash
npx next-ai-ready mcp --no-resources
```

## How it works

The MCP package (`@next-ai-ready/mcp`) is a thin adapter:

1. It reads the action registry (populated by `defineActions()`).
2. Each public action becomes an MCP tool with its name, description, and input schema.
3. Each page in the SemanticGraph becomes an MCP resource with `airead://page/<route>` URI.
4. Supplying the graph also registers `list_pages`, `get_page`, and `search_pages` automatically.
5. Action tool invocations go through `invokeAction()` — same validation, auth, and error handling as the HTTP endpoint.

## Page discovery tools

The three read-only tools are available whenever `registerAiReady(server, { graph })` receives a SemanticGraph:

| Tool           | Parameters          | Behavior and limits                                                                                                                                              |
| -------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_pages`   | `cursor?`, `limit?` | Stable route order with cursor pagination. The default limit is 20, the maximum is 50, and a cursor must be a safe absolute route no longer than 512 characters. |
| `get_page`     | `route`             | Returns metadata and full AI-ready Markdown for a safe absolute route of 1–512 characters.                                                                       |
| `search_pages` | `query`, `limit?`   | Deterministic local lexical search. Queries are 1–200 characters; the default result limit is 5 and the maximum is 20.                                           |

Search runs only over the pre-built SemanticGraph and does not require an external API, embedding service, or vector database. Use routes returned by `list_pages` or `search_pages` as input to `get_page`.

## Prerequisites

MCP requires two optional peer dependencies:

```bash
pnpm add @modelcontextprotocol/sdk mcp-handler
```

These are declared as optional in `@next-ai-ready/next`. If they are not installed, the MCP route handler returns a 501.

## Security

- Only `public: true` actions are exposed as MCP tools.
- The `auth` hook on each action runs before the handler.
- **Token auth (production):** When `NODE_ENV === "production"`, the HTTP endpoint requires a `NEXT_AI_READY_MCP_TOKEN` environment variable. Clients must send `Authorization: Bearer <token>`. Requests without a valid token receive a 401. In development, all requests are allowed.
- The stdio server runs locally and does not require token auth.
- **Stdio + auth-gated actions:** MCP stdio uses a synthetic `Request` without browser cookies or session headers. Actions with `auth: (ctx) => ...` that expect real HTTP context may return 401 over stdio — use HTTP MCP or mark demo actions `public: true` for local testing (C-70).
- You can disable auth entirely by passing `auth: false` to `createAiReadyMcpHandler()`, but this is not recommended in production.