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 } from "sourcey";

export default defineConfig({
  name: "My MCP Server",
  navigation: {
    tabs: [
      {
        tab: "MCP Reference",
        slug: "",
        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:

navigation: {
  tabs: [
    {
      tab: "MCP Reference",
      slug: "mcp",
      mcp: "./mcp.json",
    },
    {
      tab: "Guides",
      slug: "",
      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 for AI agent discovery.

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.