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.

Every Docus instance 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.

Built-in Tools

Docus 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 Docus 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

1. Open Cursor and go to Settings > Tools & MCP
2. Add the Docus MCP server configuration

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.

1. Open VS Code and access the Command Palette (Ctrl/Cmd + Shift + P)
2. Type "Preferences: Open Workspace Settings (JSON)" and select it
3. Navigate to your project's .vscode folder or create one if it doesn't exist
4. Create or edit the 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 Docus 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) }],
    }
  },
})