MCP Server

About MCP Servers

The Model Context Protocol (MCP) is an open protocol that creates standardized connections between AI applications and external services, like documentation.

This documentation template includes a built-in MCP server, preparing your content for the broader AI ecosystem where any MCP client (like Claude, Cursor, VS Code, and others) can connect to your documentation.

How MCP Servers Work

When an MCP server is connected to an AI tool, the LLM can decide to use your documentation tools during response generation:

• The LLM can proactively search your documentation while generating a response, not just when explicitly asked.
• The LLM determines when to use tools based on the context of the conversation and the relevance of your documentation.
• Each tool call happens during the generation process, allowing the LLM to incorporate real-time information from your documentation into its response.

For example, if a user asks a coding question and the LLM determines that your documentation is relevant, it can search your docs and include that information in the response without the user explicitly asking about your documentation.

Accessing Your MCP Server

Your MCP server is automatically available at the /mcp path of your documentation URL.

Disable the MCP Server

If you want to disable the MCP server, you can do so in your nuxt.config.ts:

export default defineNuxtConfig({
  mcp: {
    enabled: false,
  },
})

Built-in Tools

This template provides two tools out of the box that allow any LLM to discover and read your documentation:

list-pages

Lists all documentation pages with their titles, paths, and descriptions. AI assistants should call this first to discover available content.

get-page

Retrieves the full markdown content of a specific documentation page.

Setup

The MCP server uses HTTP transport and can be installed in different AI assistants.

Claude Code

Add the server using the CLI command:

claude mcp add --transport http my-docs https://docs.example.com/mcp

Cursor

Or manually create/update .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "my-docs": {
      "type": "http",
      "url": "https://docs.example.com/mcp"
    }
  }
}

Visual Studio Code

Ensure you have GitHub Copilot and GitHub Copilot Chat extensions installed.

Or manually create/update the .vscode/mcp.json file:

{
  "servers": {
    "my-docs": {
      "type": "http",
      "url": "https://docs.example.com/mcp"
    }
  }
}

Windsurf

1. Open Windsurf and navigate to Settings > Windsurf Settings > Cascade
2. Click the Manage MCPs button, then select the View raw config option
3. Add the following configuration:

{
  "mcpServers": {
    "my-docs": {
      "type": "http",
      "url": "https://docs.example.com/mcp"
    }
  }
}

Zed

1. Open Zed and go to Settings > Open Settings
2. Navigate to the JSON settings file
3. Add the following context server configuration:

{
  "context_servers": {
    "my-docs": {
      "source": "custom",
      "command": "npx",
      "args": ["mcp-remote", "https://docs.example.com/mcp"],
      "env": {}
    }
  }
}

Customization

Since this template uses the @nuxtjs/mcp-toolkit module, you can extend the MCP server with custom tools, resources, prompts, and handlers.

Adding Custom Tools

Create new tools in the server/mcp/tools/ directory:

import { z } from 'zod'

export default defineMcpTool({
  description: 'Search documentation by keyword',
  inputSchema: {
    query: z.string().describe('The search query'),
  },
  handler: async ({ query }) => {
    const results = await searchDocs(query)
    return {
      content: [{ type: 'text', text: JSON.stringify(results) }],
    }
  },
})

Adding Resources

Expose files or data sources as MCP resources in the server/mcp/resources/ directory. The simplest way is using the file property:

export default defineMcpResource({
  file: 'CHANGELOG.md',
  metadata: {
    description: 'Project changelog',
  },
})

This automatically handles URI generation, MIME type detection, and file reading.

Adding Prompts

Create reusable prompts for AI assistants in the server/mcp/prompts/ directory:

import { z } from 'zod'

export default defineMcpPrompt({
  description: 'Get help with migrating between versions',
  inputSchema: {
    fromVersion: z.string().describe('Current version'),
    toVersion: z.string().describe('Target version'),
  },
  handler: async ({ fromVersion, toVersion }) => {
    return {
      messages: [{
        role: 'user',
        content: {
          type: 'text',
          text: `Help me migrate from version ${fromVersion} to ${toVersion}. What are the breaking changes and steps I need to follow?`,
        },
      }],
    }
  },
})

Adding Custom Handlers

Handlers allow you to create separate MCP endpoints with their own tools, resources, and prompts. This is useful for exposing different capabilities at different routes.

For example, you could have:

• /mcp - Main documentation MCP server
• /mcp/migration - Dedicated MCP server for migration assistance

import { z } from 'zod'

const migrationTool = defineMcpTool({
  name: 'migrate-v3-to-v4',
  description: 'Migrate code from version 3 to version 4',
  inputSchema: {
    code: z.string().describe('The code to migrate'),
  },
  handler: async ({ code }) => {
    // Migration logic
    return {
      content: [{ type: 'text', text: migratedCode }],
    }
  },
})

export default defineMcpHandler({
  route: '/mcp/migration',
  name: 'Migration Assistant',
  version: '1.0.0',
  tools: [migrationTool],
})

Overwriting Built-in Tools

You can override the default list-pages or get-page tools by creating a tool with the same name in your project:

import { z } from 'zod'

export default defineMcpTool({
  description: 'Custom list pages implementation',
  inputSchema: {
    locale: z.string().optional(),
    category: z.string().optional(),
  },
  handler: async ({ locale, category }) => {
    const pages = await getCustomPageList(locale, category)
    return {
      content: [{ type: 'text', text: JSON.stringify(pages) }],
    }
  },
})