---
title: "Model Context Protocol (MCP) · Nuxt AI Ready · Nuxt SEO"
canonical_url: "https://nuxtseo.com/docs/ai-ready/guides/mcp"
last_updated: "2026-08-16T09:50:32.587Z"
meta:
  description: "Connect AI agents like Claude to your Nuxt site via MCP servers with built-in tools and resources."
  "og:description": "Connect AI agents like Claude to your Nuxt site via MCP servers with built-in tools and resources."
  "og:title": "Model Context Protocol (MCP) · Nuxt AI Ready · Nuxt SEO"
---

Nuxt SEO on GitHub

Switch to AI ReadySwitch to Nuxt SEOSwitch to RobotsSwitch to SitemapSwitch to OG ImageSwitch to Schema.orgSwitch to Link CheckerSwitch to SEO UtilsSwitch to Site ConfigSwitch to Skew Protection

**Core Concepts**

# **Model Context Protocol (MCP)**

[**~~Model Context Protocol (MCP)~~**](https://modelcontextprotocol.io/) support via [`**@nuxtjs/mcp-toolkit**`](https://github.com/nuxt-modules/mcp-toolkit).

Your site exposes tools and resources that AI agents like Claude can query for page data and search.

## Installation

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

nuxt.config.ts

```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**` peer:

```bash
pnpm add agents
```

## 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**` publishes its card at `**/mcp/server-card**`. Custom MCP routes and `**app.baseURL**` are preserved.

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**` 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**`, and support `**If-None-Match**` revalidation.

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

## Connection

Add to Claude Desktop config (`**~/Library/Application Support/Claude/claude_desktop_config.json**` on macOS):

```json
{
  "mcpServers": {
    "my-site": {
      "command": "npx",
      "args": ["-y", "@nuxtjs/mcp-client", "https://example.com/mcp"]
    }
  }
}
```

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

**Response:**

```json
{
  "pages": [
    {
      "route": "/docs/getting-started",
      "title": "Getting Started",
      "description": "Quick start guide",
      "headings": "h1:Getting Started|h2:Installation",
      "updatedAt": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 50,
  "limit": 20,
  "offset": 0,
  "hasMore": false
}
```

### `**search_pages**`

Full-text search across pages via SQLite FTS5. Searches title, description, route, headings, keywords, and content. Cached 5 minutes.

**Parameters:**

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

**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**`**. Page listing as JSON. Same data as `**list_pages**` tool. Cached 1 hour.

Use resources when agents need static data without parameters.

## 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~~**](https://nuxtseo.com/docs/ai-ready/guides/runtime-indexing). Test the MCP server with `**nuxi build**` and a running Nitro server. A fully static `**nuxi generate**` deployment cannot host the Toolkit server route.

## Configuration

`**aiReady.tools**` configures definitions shared by MCP and WebMCP. Transport settings stay with the attachment:

nuxt.config.ts

```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**` 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**`:

nuxt.config.ts

```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**` and the MCP route, then synchronizes MCP Toolkit to the same runtime identity. A pre-existing human-readable `**mcp.name**` is retained as the card title.

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

**Was this page helpful?**

### **Related **

[**Installation**](https://nuxtseo.com/docs/ai-ready/getting-started/installation)

[**Configuration**](https://nuxtseo.com/docs/ai-ready/api/config)

[**llms.txt Guide**](https://nuxtseo.com/learn-seo/nuxt/controlling-crawlers/llms-txt)

[**llms.txt Generation** Configure llms.txt and llms-full.txt output for AI discovery.](https://nuxtseo.com/docs/ai-ready/guides/llms-txt) [**Runtime Sync (Optional)** Opt-in runtime page indexing for sites with dynamic content.](https://nuxtseo.com/docs/ai-ready/guides/runtime-indexing)