Model Context Protocol (MCP)

Use Model Context Protocol (MCP) to let clients list, search, and read your indexed pages. Install @nuxtjs/mcp-toolkit to host the MCP endpoint in your Nuxt server.

Installation

The site tools read stored pages from the runtime database. The database needs drizzle-orm, an optional peer dependency.

npx nuxt module add @nuxtjs/mcp-toolkit
npx nypm add drizzle-orm@1.0.0-rc.4

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.

If the app installs Toolkit but not drizzle-orm, the build fails and names the install command. If you use Toolkit only for your own tools, set aiReady: { database: false }. The site tools then stay off and the app does not need drizzle-orm.

See @nuxtjs/mcp-toolkit docs for server configuration and transport options.

Cloudflare Workers and Pages also require Toolkit's agents peer:

pnpm add agents

Connection

Connect your MCP client's Streamable HTTP transport to https://example.com/mcp. 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 before changing the client configuration.

Client setup differs. Follow your client's remote MCP instructions and the Toolkit documentation.

Tools

list_pages

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

Parameters:

Example decoded response:

{
  "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 uses case-insensitive matching across title, description, headings, and content, with score: 0. The tool caches results for five minutes.

Parameters:

Example decoded response:

[
  {
    "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.

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

Prerender at least the pages you want to expose, or enable 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:

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:

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.

Server discovery

Runtime MCP servers publish a SEP-2127 Server Card beside the Streamable HTTP endpoint. A server at /mcp publishes its card at /mcp/server-card. Custom MCP routes and app.baseURL are preserved.

The module also serves the same card at /.well-known/mcp/server-card.json and /.well-known/mcp.json. Agent readiness scanners, such as Cloudflare's isitagentready, look for a card at these paths.

When site.url is set, the module publishes the same catalog at two origin paths:

• /.well-known/ard.json, the ARD v0.91 discovery path.
• /.well-known/ai-catalog.json, the AI Catalog discovery path.

Each entry includes the Server Card's title, description, identifier, media type, and URL. If the card has no title, the entry uses its server name. Agents can find the Server Card without knowing the MCP route.

curl -H 'Accept: application/mcp-server-card+json' https://example.com/mcp/server-card
curl -H 'Accept: application/mcp-server-card+json' https://example.com/.well-known/mcp/server-card.json
curl -H 'Accept: application/ai-catalog+json' https://example.com/.well-known/ai-catalog.json
curl -H 'Accept: application/ai-catalog+json' https://example.com/.well-known/ard.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.

llms.txt links the card at /.well-known/mcp/server-card.json, not the MCP endpoint. The endpoint answers GET with 405 or 406, so llms.txt link checkers count an endpoint link as broken. The card link's description names the endpoint URL. With aiReady.mcpServerCard: false, llms.txt has no MCP entry. The API Catalog still lists the endpoint.

If you enable built-in MCP tools, the module adds usage guidance to the handshake and the llms.txt card link. Set mcp.instructions to provide your own handshake guidance. Use aiReady.llmsTxt.notes to explain which product tasks your site supports.

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 for hook payloads and examples. Custom Toolkit paths also work with Nuxt AI Ready. See custom paths.