DEV Community

Cover image for MCP Playbook: Auto-generated docs and a live playground for your MCP servers
capscode
capscode

Posted on Originally published at capscode.in

MCP Playbook: Auto-generated docs and a live playground for your MCP servers

#mcp #devchallenge #webdev #ai

MCP Playbook: Auto-generated docs and a live playground for your MCP servers

If you've built an MCP (Model Context Protocol) server, you know the drill. You ship it, then your teammates ask: "Which tools does this expose? What parameters do they take? How do I actually try them?"

You end up writing docs by hand, they go stale the moment you add a new tool, and nobody knows how to test anything without cloning the repo and reading the source.

MCP Playbook solves that. It connects to your MCP server, reads every tool's schema, and generates an interactive docs site with a live "Try it" playground — automatically. Think Storybook or Swagger UI, but for MCP tools.

🔗 Docs: https://rahulnag.github.io/mcp-playbook/
▶️ Live playground: https://rahulnag.github.io/mcp-playbook/playground/
📦 npm: https://www.npmjs.com/package/mcp-playbook

The problem

MCP is exploding right now. Every week there's a new server exposing tools for file systems, databases, APIs, GitHub, Slack, you name it. But the developer experience around discovering and testing those tools is still rough.

You have two options today:

  1. Read the source code and figure out the tool schemas yourself
  2. Use MCP Inspector, which is great for debugging but lives on localhost and is designed for protocol-level inspection, not for sharing with your team

Neither gives you shareable, always-current, try-it-in-the-browser docs.

That's the gap MCP Playbook fills.

What you get

Connect MCP Playbook to your server and it generates a web UI with:

  • Docs for every tool and parameter — types, required/optional, defaults, descriptions, allowed values
  • A "Try it" form built from each tool's schema — run any tool against your real server from the browser
  • Saved examples your team can load with one click
  • Schema viewer with the raw JSON Schema, ready to copy
  • A static site build you can deploy as a URL and share with anyone

No hand-written docs. No drift. Every run reads the latest tools straight from your server over the standard MCP protocol.

Quick start

You need Node.js 18+ and an MCP server in any language (Node, Python, Go, Rust — it just talks MCP).

1. Install 

npm install -D mcp-playbook
Enter fullscreen mode Exit fullscreen mode

Install it in your project — the config file imports from the package, so it needs to be in your node_modules.

2. Create a config 

npx mcp-playbook init
Enter fullscreen mode Exit fullscreen mode

This creates playbook.config.ts and never overwrites an existing one.

3. Point it at your server

Open the config and change command / args to whatever you'd normally type to start your server:

import { defineConfig } from 'mcp-playbook'

export default defineConfig({
  servers: [
    {
      name:      'My Server',
      transport: 'stdio',        // Playbook starts the server for you
      command:   'node',
      args:      ['./server.js'],
    },
  ],
})
Enter fullscreen mode Exit fullscreen mode

Already have a running HTTP server? Just point at the URL:

{
  name:      'Remote API',
  transport: 'http',
  url:       'http://localhost:3001/mcp',
}
Enter fullscreen mode Exit fullscreen mode

4. Run it 

npx mcp-playbook dev
Enter fullscreen mode Exit fullscreen mode

Your browser opens at http://localhost:4242 with every tool listed, docs rendered, and Run tool working against your real server. Edit the config while it runs and the page reloads.

5. Deploy it 

npx mcp-playbook build
Enter fullscreen mode Exit fullscreen mode

This bakes your tools into a static site in playbook-dist/. Upload it to GitHub Pages, Vercel, Netlify, S3, nginx — anywhere that serves static files. On the hosted site, Docs, Examples and Schema work; Run tool is disabled (no live server behind a static site).

How it works

MCP Playbook speaks the standard MCP protocol. Depending on your server, it uses one of three transports:

Your server Transport
Runs locally as a command (node server.js, python server.py) stdio
Is already running at a URL like http://…/mcp http
Is already running with the older SSE transport sse

For stdio servers, Playbook starts your server for you and talks to it over stdin/stdout. For http/sse servers, it connects to the running instance. Either way, it calls tools/list and reads every tool's schema — that's the entire integration.

No SDK changes. No annotations. No decorators. If it speaks MCP, it works.

A config that does more

Everything beyond servers is optional, but a few fields are worth knowing about.

Environment variables for stdio servers

If your server reads process.env.API_KEY, you need to pass it through explicitly. A stdio server only sees a small basic set of env vars plus whatever you list — for safety:

env: {
  API_KEY: process.env.API_KEY!,   // reads from your terminal, not the file
  DB_URL:  process.env.DB_URL!,
},
Enter fullscreen mode Exit fullscreen mode

The process.env.X pattern keeps secrets out of the config and out of git.

Headers for http / sse servers

For remote servers that need auth, use headers:

headers: {
  Authorization: `Bearer ${process.env.API_TOKEN}`,
},
Enter fullscreen mode Exit fullscreen mode

Rule of thumb: env for stdio servers (passed to the process Playbook starts). headers for http/sse servers (sent over the network).

Saved examples

Examples show up in a tool's Examples tab. Click Load → to copy them into the Try it form:

examples: {
  get_user: [
    {
      label:       'Fetch admin user',
      input:       { userId: 'usr_admin_001' },
      description: 'Look up the main admin account',
    },
  ],
},
Enter fullscreen mode Exit fullscreen mode

The key is the tool name exactly as your server defines it.

Tags for organization

Tags show as badges on tool pages and match the sidebar search:

tags: {
  'User management': ['get_user', 'create_user'],
  'Admin':           ['purge_cache'],
},
Enter fullscreen mode Exit fullscreen mode

Multiple servers, one UI

List as many servers as you want in servers. They all show up in one sidebar, with per-server filtering and connection status (green dot = connected, red = couldn't reach).

Server recipes

Copy the one that matches your setup:

// Node.js
{ name: 'My Server', transport: 'stdio', command: 'node', args: ['./dist/server.js'] }

// TypeScript with tsx
{ name: 'My Server', transport: 'stdio', command: 'npx', args: ['tsx', './src/server.ts'] }

// Python
{ name: 'My Server', transport: 'stdio', command: 'python', args: ['server.py'] }

// Python in a virtualenv
{ name: 'My Server', transport: 'stdio', command: './.venv/bin/python', args: ['server.py'] }

// Python with uv
{ name: 'My Server', transport: 'stdio', command: 'uv', args: ['run', 'server.py'] }

// Compiled binary (Go, Rust…)
{ name: 'My Server', transport: 'stdio', command: './bin/my-server' }

// Published npm MCP server
{ name: 'Filesystem', transport: 'stdio', command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', './'] }

// Running HTTP server with auth
{ name: 'My Server', transport: 'http',
  url: 'https://api.example.com/mcp',
  headers: { Authorization: `Bearer ${process.env.API_TOKEN}` } }
Enter fullscreen mode Exit fullscreen mode

Deploying the docs

mcp-playbook build produces a folder of plain HTML, JS and images:

playbook-dist/
├── index.html          the page
├── assets/             JS and CSS
├── data.json           your tools, baked in at build time
├── favicon.svg
└── og-image.png        link-preview image
Enter fullscreen mode Exit fullscreen mode

Upload the contents of that folder to any static host. A few one-liners:

# GitHub Pages: use the workflow in the docs
# Vercel
vercel deploy playbook-dist --prod

# Netlify
netlify deploy --dir playbook-dist --prod

# Cloudflare Pages
npx wrangler pages deploy playbook-dist

# AWS S3
aws s3 sync playbook-dist s3://your-bucket-name --delete

# Your own nginx
npx mcp-playbook build --output /var/www/mcp-docs
Enter fullscreen mode Exit fullscreen mode

Two things to know:

  • Secrets are never written to the output. Values from env and headers stay out of the built files.
  • Your servers must be reachable during build. Stdio servers get started; http/sse servers must already be running.

Set siteUrl in your config to your deployed URL, and shared links on LinkedIn, X, and Slack will show a proper preview image.

How it compares to MCP Inspector

They solve different problems and work well together:

MCP Inspector MCP Playbook
Made for Debugging the protocol while you build Documenting and sharing tools with your team
Shareable URL / static site ❌ localhost only ✅ mcp-playbook build
Examples saved in git ❌ ✅
Many servers in one view ❌ one at a time ✅
Raw JSON-RPC, OAuth debugging ✅ ❌ not the goal

Inspector while you're building. Playbook when your team (or your customers) need to browse and try your tools.

What's on the roadmap

  • 🗓 Resources and prompts (not just tools)
  • 🗓 Theming via theme
  • 🗓 Tool call history
  • 🗓 Export calls as curl / fetch / SDK snippets
  • 🗓 Schema diff when tools change
  • 🗓 OAuth 2.0 login in the UI
  • 🗓 Embeddable <MCPPlaybook /> React component
  • 🔭 Mock mode (no real server needed)

Shipped already: docs, Try it, Examples, Schema tabs, stdio / HTTP / SSE transports, live reload, static build, multi-server dashboard.

Try it 

npm install -D mcp-playbook
npx mcp-playbook init
npx mcp-playbook dev
Enter fullscreen mode Exit fullscreen mode

That's it. Three commands from "I have an MCP server" to "my whole team can browse and run every tool."

Contributions are very welcome — bug reports, docs fixes, features. There's a contributing guide with setup and project structure.

If MCP Playbook saves you time, a ⭐ on GitHub goes a long way. And if you build something with it, I'd love to hear about it in the comments.

Top comments (0)