---
title: "Model Context Protocol (MCP)"
description: "Connect AI agents like Claude to your Nuxt site via MCP servers with built-in tools and resources."
canonical_url: "https://nuxtseo.com/docs/ai-ready/guides/mcp"
last_updated: "2026-09-25T20:12:09.462Z"
---

Use [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) to let clients list, search, and read your indexed pages.
Install [`@nuxtjs/mcp-toolkit`](https://github.com/nuxt-modules/mcp-toolkit) to host the MCP endpoint in your Nuxt server.

## Installation

```bash
npx nuxi module add @nuxtjs/mcp-toolkit
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: [
    'nuxt-ai-ready',
    '@nuxtjs/mcp-toolkit',
  ],
  mcp: {
    enabled: true,
  },
})
```

Module order does not matter. Nuxt AI Ready also detects Toolkit installations declared as a later module's dependency.

See [@nuxtjs/mcp-toolkit docs](https://mcp-toolkit.nuxt.dev/) for server configuration and transport options.

Cloudflare Workers and Pages also require Toolkit's `agents`{lang="bash"} peer:

```bash
pnpm add agents
```

## Connection

Connect your MCP client's Streamable HTTP transport to `https://example.com/mcp`{lang="text"}.
Use your configured Toolkit route if you changed it.

Start with `list_pages`, then pass a returned route to `get_page_markdown`.
If the list is empty, check [Data Availability](#data-availability) before changing the client configuration.

Client setup differs. Follow your client's remote MCP instructions and the [Toolkit documentation](https://mcp-toolkit.nuxt.dev/).

## Tools

### `list_pages`

Returns page metadata as JSON with pagination. Cached 1 hour.

**Parameters:**

| Param    | Type     | Description                                     |
| -------- | -------- | ----------------------------------------------- |
| `limit`  | `number` | Max pages to return, from 1 to 50 (default: 20) |
| `offset` | `number` | Skip first N pages (default: 0)                 |

**Example decoded response:**

```json
{
  "pages": [
    {
      "route": "/docs/getting-started",
      "title": "Getting Started",
      "description": "Quick start guide",
      "headings": [{ "h1": "Getting Started" }, { "h2": "Installation" }]
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0,
  "hasMore": false
}
```

### `search_pages`

Searches stored pages. SQLite-compatible databases use FTS5 across title, description, route, headings, keywords, and content.
[PostgreSQL](https://postgresql.org) uses case-insensitive matching across title, description, headings, and content, with `score: 0`. The tool caches results for five minutes.

**Parameters:**

| Param   | Type     | Description                             |
| ------- | -------- | --------------------------------------- |
| `query` | `string` | Search query                            |
| `limit` | `number` | Max results, from 1 to 50 (default: 10) |

**Example decoded response:**

```json
[
  {
    "route": "/docs/installation",
    "title": "Installation",
    "description": "Install the module",
    "score": 0.15
  }
]
```

### `get_page_markdown`

Returns the indexed markdown for one route. Cached 5 minutes.

| Param   | Type     | Description                                 |
| ------- | -------- | ------------------------------------------- |
| `route` | `string` | Page route, with or without a leading slash |

```md
# Installation

Install the module...
```

Missing pages return a tool error instead of an empty response.

## Resources

**`resource://nuxt-ai-ready/pages`** returns the same page metadata as `list_pages`, cached for one hour.
It accepts `?limit=N&offset=N`, with a default limit of 100 and a maximum of 500.
Use the resource when your client reads MCP resources instead of calling tools.

## Data Availability

MCP tools read the runtime database. On the first MCP request, Nuxt AI Ready restores page data produced during the build before the Toolkit resolves its tools.

| Environment    | Data Source                                    |
| -------------- | ---------------------------------------------- |
| **Dev mode**   | Empty (no prerender data)                      |
| **Production** | Build index restored into the runtime database |

Prerender at least the pages you want to expose, or enable [runtime indexing](/docs/ai-ready/guides/runtime-indexing). Test the MCP server with `nuxi build`{lang="bash"} and a running Nitro server. A fully static `nuxi generate`{lang="bash"} deployment cannot host the Toolkit server route.

## Configuration

`aiReady.tools`{lang="ts"} configures definitions shared by MCP and WebMCP. Transport settings stay with the attachment:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  aiReady: {
    tools: {
      listPages: {
        defaultLimit: 10,
        mcp: { enabled: false },
      },
      searchPages: {
        defaultLimit: 5,
      },
    },
    mcp: {
      resources: false,
    },
    webmcp: true,
  }
})
```

Here, `list_pages` stays available to WebMCP but is left off the regular MCP server. `search_pages` defaults to five results on both transports. Set `aiReady.mcp.tools`{lang="ts"} to `false` to detach all three tools from MCP Toolkit.

These settings only affect Nuxt AI Ready definitions. Tools added directly through MCP Toolkit keep their own config.

Configure optional card metadata under `aiReady.mcpServerCard`{lang="ts"}:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  aiReady: {
    mcpServerCard: {
      name: 'com.example/docs-mcp',
      title: 'Acme docs MCP',
      websiteUrl: 'https://example.com/docs/mcp',
      cacheMaxAge: 900,
    },
  },
})
```

The card name must use reverse-DNS/server format. Without an explicit name, Nuxt AI Ready derives one from `site.url`{lang="ts"} and the MCP route, then synchronizes MCP Toolkit to the same runtime identity. A pre-existing human-readable `mcp.name`{lang="ts"} is retained as the card title.

## Server discovery

Runtime MCP servers publish a [SEP-2127 Server Card](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) beside the Streamable HTTP endpoint. A server at `/mcp`{lang="bash"} publishes its card at `/mcp/server-card`{lang="bash"}. Custom MCP routes and `app.baseURL`{lang="ts"} are preserved.

::warning
Server Cards and AI Catalog discovery are experimental. SEP-2127 remains a draft, and its mandated canonical schema URL may return 404 until MCP publishes the v1 schema upstream.
::

When `site.url`{lang="ts"} is set, the module also publishes [`/.well-known/ai-catalog.json`](https://github.com/Agent-Card/ai-catalog) at the origin. Agents can use this small catalog to find the Server Card without knowing the MCP route.

```bash
curl -H 'Accept: application/mcp-server-card+json' https://example.com/mcp/server-card
curl -H 'Accept: application/ai-catalog+json' https://example.com/.well-known/ai-catalog.json
```

The card publishes static identity and connection metadata, including every protocol version supported by the installed MCP SDK. Tools, resources, prompts and capabilities remain discoverable through the live MCP protocol. Responses include CORS headers, a strong `ETag`{lang="http"}, and support `If-None-Match`{lang="http"} revalidation.

Set `aiReady.mcpServerCard`{lang="ts"} to `false` to remove the card and its AI Catalog entry. A fully static `nuxi generate`{lang="bash"} deployment does not publish either because it cannot host an MCP server.

## Extending the Server

Use the Toolkit hooks when its config API is too coarse:

- `mcp:config:resolved` can adjust the resolved tools, resources and server config.
- `mcp:server:created` exposes the low-level MCP server for custom registration.

See the [Toolkit hooks guide](https://mcp-toolkit.nuxt.dev/advanced/hooks) for hook payloads and examples. Custom Toolkit paths also work with Nuxt AI Ready. See [custom paths](https://mcp-toolkit.nuxt.dev/advanced/custom-paths).

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.