XMTP docs MCP

A lightweight, docs-only MCP server that exposes XMTP documentation as searchable tools for MCP-compatible clients like Claude Code.

This project is intended as an internal beta. It provides structured, queryable access to XMTP docs for LLM-assisted development workflows.

Quickstart for Claude Code

1. Add the MCP server to Claude Code using npx:

   claude mcp add --transport stdio xmtp-docs -- npx -y github:xmtp/xmtp-docs-mcp

2. Start Claude Code:

   claude

3. Inside Claude Code, run:

   /mcp

You should see the xmtp-docs server and its tool endpoints listed.

Quickstart for Cursor (per-project)

1. In the root of your project repo where you want to use the XMTP docs MCP (e.g., my-chat-app repo), create a file at:

   mkdir -p .cursor
   touch .cursor/mcp.json

2. Add this configuration to .cursor/mcp.json:

{
  "mcpServers": {
    "xmtp-docs": {
      "command": "npx",
      "args": ["-y", "github:xmtp/xmtp-docs-mcp"]
    }
  }
}

Tip

If Cursor doesn’t recognize mcpServers in your version, try mcp_servers as the top-level key instead.

3. Restart Cursor.

4. Select a Claude-based agent (such as Sonnet) for reliable MCP-backed answers. Some agents may not invoke MCP tools.

Quickstart for VS Code (per-workspace)

1. Install the GitHub Copilot extension (if not already installed).

2. Open your VS Code settings and add the MCP server configuration:

   • Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
   • Search for "MCP: Add Server..."
   • Choose "Command (stdio)"
   • Enter the command: npx -y github:xmtp/xmtp-docs-mcp

   Alternatively, add a .vscode/mcp.json file containing:

   {
     "servers": {
       "xmtp-docs": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "github:xmtp/xmtp-docs-mcp"]
       }
     },
     "inputs": []
   }

Docs source

The server loads the full XMTP LLM docs bundle covering how to build chat apps and agents: https://docs.xmtp.org/llms/llms-full.txt

Fork this for your own docs

This server is designed as a template for technical documentation teams that want to provide MCP servers for their own documentation. If you maintain technical docs and want to make them queryable by LLM clients, you can fork this repo and point it at your own documentation.

What you need

A docs bundle in plain text or markdown format (like llms-full.txt).

• Should be structured with markdown headings (#, ##, ###) for best chunking
• Can be hosted on GitHub, your docs site, or served locally
• See XMTP's generate_llms_full.py for an example script that generates a docs bundle from a docs site

Fork setup

1. Fork this repository to your-org/your-docs-mcp

2. Update package.json:

   {
     "name": "your-docs-mcp",
     "description": "Docs-only MCP server for YourProduct documentation"
   }

3. Update the URL in src/index.ts:

   const DOC_URL = "https://your-domain.com/path/to/your-docs.txt";

4. Update src/index.ts to customize the server name:

   const server = new McpServer({
     name: "your-docs-mcp",
     version: "1.0.0",
   });

5. Build:

   npm install
   npm run build

6. Publish to your repo

Project structure

File/Folder	Purpose
src/index.ts	The brain of the server: Loads docs, chunks them, defines MCP tools, handles search
src/cli.ts	Entry point: Eight lines that start the server
dist/	Compiled JavaScript output (generated by npm run build)
package.json	Dependencies, scripts, and package metadata
tsconfig.json	TypeScript compiler settings
README.md	This documentation
LICENSE	CC0 1.0 Universal

How it's built

This MCP server is a lightweight, single-file implementation built on the official Model Context Protocol SDK. Here's how the key components work together.

Core components

MCP server framework

• Built on @modelcontextprotocol/sdk — the official MCP SDK from Anthropic
• Uses StdioServerTransport for communication via standard input/output, making it compatible with any MCP client
• Registered as a CLI tool via bin in package.json, enabling npx execution

Schema validation

• Uses Zod for runtime validation of tool parameters
• Type-safe schemas ensure correct inputs for both search_xmtp_docs and get_xmtp_doc_chunk tools

Document loading

• Fetches XMTP docs from DOC_URL at startup and keeps them in memory

Document chunking

• Splits documentation text into searchable chunks based on markdown headings (#, ##, ###, etc.)
• Each chunk gets a unique numeric ID and retains its section title
• Simple, deterministic algorithm that preserves document structure

Search algorithm

• Keyword-based scoring that counts query occurrences in chunk title + text
• Supports both full query phrases and individual tokens
• Returns top N results sorted by relevance score

Tool endpoints

The server exposes two MCP tools that LLM clients can invoke:

1. search_xmtp_docs — Returns ranked search results with previews
2. get_xmtp_doc_chunk — Fetches full content of a specific chunk by ID

Both tools use Zod schemas for parameter validation and return JSON-formatted responses.

Local development

This is only needed if you’re working on the MCP server itself. End users should use the Quickstart setup instead.

npm install
npm run build
npm run dev

The server will start and wait for stdio input (this is expected).