# MCP Server \[Expose your docs and source code to AI assistants]

## Overview

Vocs includes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server. When enabled, AI clients can read, search, and browse your docs — and optionally source repositories you choose to expose — from a single endpoint at `/api/mcp`.

The server is read-only. Vocs supports Streamable HTTP (`POST /api/mcp`) and the older HTTP+SSE transport (`GET /api/mcp`).

## Setup

::::steps

### Enable the server

```ts [vocs.config.ts]
export default defineConfig({
  mcp: { enabled: true }, // [!code focus]
})
```

### Connect your AI client

Ask your agent to add the MCP server. It will edit the right config file for your client (Claude Desktop, Cursor, VS Code, etc.):

```txt
Add this MCP server to my AI client config:

https://docs.example.com/api/mcp
```

Use `http://localhost:5173/api/mcp` while developing locally.

### Verify

Ask the agent to list and read pages. With `mcp.enabled`, you should see the tools `list_pages`, `read_page`, and `search_docs`.

```txt
List the pages from the Vocs MCP server, then read /introduction/getting-started.
```

::::

## Recipes

### Expose Source Code

Add one or more `sources` to let assistants browse implementation alongside your docs.

```ts [vocs.config.ts]
import { defineConfig, McpSource } from 'vocs/config'

export default defineConfig({
  mcp: {
    enabled: true,
    sources: [ // [!code focus:4]
      McpSource.github({ name: 'vocs', repo: 'wevm/vocs' }),
      McpSource.github({ name: 'viem', repo: 'wevm/viem', paths: ['src', 'site'] }),
    ],
  },
})
```

This adds the source tools: `list_sources`, `list_source_files`, `read_source_file`, `get_file_tree`, and `search_source` (when the adapter supports it).

Set `GITHUB_TOKEN` for higher rate limits and to enable authenticated code search.

### Build a Custom Adapter

For non-GitHub backends (internal repos, databases, remote APIs), implement an adapter with `McpSource.from()`.

```ts
McpSource.from({
  name: 'workspace',
  type: 'custom',
  async listFiles(path) {
    return [{ name: 'index.ts', path: 'src/index.ts', type: 'file' }]
  },
  async readFile(path) {
    return '// file content'
  },
  async getTree(options) {
    return { files: [], truncated: false }
  },
})
```

## Tips

* The MCP server only exposes paths you explicitly configure. If your site is private, put it behind your existing auth layer.
* `search_docs` is text search over page files, not a semantic embedding index.
* Local URLs like `http://localhost:5173/api/mcp` only work if the client runs on the same machine. For remote clients, deploy first or expose your dev server through a secure tunnel.

## See More

<Cards>
  <Card title="mcp" description="Full mcp.enabled, mcp.sources, and transport options." icon="plug" to="/reference/site-config#mcp" />

  <Card title="McpSource" description="Built-in GitHub adapter and the McpSource.from() factory for custom sources." icon="github" to="/reference/site-config#mcpsource" />

  <Card title="Agent Support" description="Markdown rendering and llms.txt files served to AI agents." icon="bot" to="/features/agent-support" />

  <Card title="Ask AI" description="In-page AI menu that surfaces the MCP URL for users to copy." icon="sparkles" to="/features/ask-ai" />
</Cards>