Tutorial: Document Your MCP Server

This tutorial walks through generating documentation for an MCP server. You'll snapshot a running server, configure sourcey, and build a complete reference site.

Prerequisites

• Node.js 20 or later
• A running MCP server (or you can hand-write an mcp.json)

1. Snapshot your server

Install mcp-parser and snapshot your running server:

npx mcp-parser snapshot --stdio "node my-server.js" -o mcp.json

For servers that use SSE or streamable HTTP:

npx mcp-parser snapshot --sse http://localhost:3000/sse -o mcp.json
npx mcp-parser snapshot --http http://localhost:3000/mcp -o mcp.json

This creates an mcp.json file capturing your server's tools, resources, and prompts. You can also write mcp.json by hand if you prefer.

2. Validate the snapshot

npx mcp-parser validate ./mcp.json

Valid: no issues found.

3. Create a sourcey project

npm install sourcey

Create sourcey.config.ts:

import { defineConfig, mcp } from "sourcey";

export default defineConfig({
  name: "My MCP Server",
  navigation: {
    tabs: [
      {
        tab: "MCP Reference",
        slug: "",
        source: mcp("./mcp.json"),
      },
    ],
  },
});

4. Preview locally

npx sourcey dev

Open http://localhost:4400. You should see your tools in the sidebar with purple method pills, resources in green, and prompts in blue.

5. Add markdown guides

Create an introduction.md alongside your config:

---
title: Introduction
description: Getting started with the MCP server.
---

Your server description and usage instructions here.

Add a guides tab to your config:

import { defineConfig, markdown, mcp } from "sourcey";

export default defineConfig({
  navigation: {
    tabs: [
      {
        tab: "MCP Reference",
        slug: "mcp",
        source: mcp("./mcp.json"),
      },
      {
        tab: "Guides",
        slug: "",
        source: markdown({
          groups: [{ group: "Getting Started", pages: ["introduction"] }],
        }),
      },
    ],
  },
});

6. Build and deploy

npx sourcey build

The dist/ directory contains your complete site. The build also emits llms.txt and llms-full.txt as portable context views of the same documentation graph.

Deploy the output to any static host: GitHub Pages, Netlify, Vercel, S3, or your own server.

Example

The Cheese Store MCP tab is a working example with tools, resources, resource templates, and prompts. See the source on GitHub for the config and mcp.json.