MCPAlpha
Reference MCP (Model Context Protocol) tools and resources in your docs pages
To describe your MCP server, point xyd at a remote MCP endpoint or commit a local JSON manifest that matches the tools/list + resources/list shape.
Source can be an http://, https://, or sse:// URL — or a path to a local JSON file.
A URL is read over streamable HTTP, the way MCP clients connect: xyd sends initialize, keeps the
session the server issues (Mcp-Session-Id) and the protocol version it answers
(Mcp-Protocol-Version), reads answers sent as JSON or as an event stream, follows nextCursor
across pages, and ends the session afterwards. A server that does not implement initialize is read
with plain tools/list and resources/list requests.
To serve an API as an MCP server in the first place, see MCP Server.
Configuration Quickstart
The fastest way to get started with MCP is to add an mcp field to api in the settings file.
This field can contain either a path to a local manifest in your docs, or the URL of a live MCP server:
This will create a new route based on your MCP source at docs/api/mcp/*.
The local manifest mirrors the wire format of tools/list + resources/list. See the sample for the exact shape.
Multi Spec Configuration
Documenting more than one MCP server is also possible:
Thanks to this configuration, you'll have two routes: docs/api/primary/* and docs/api/secondary/*.
Authentication
Bearer tokens are passed via info.token and sent as Authorization: Bearer <token>. Use $ENV_VAR to keep secrets out of docs.json:
info.headers is merged on top of the default JSON-RPC headers — useful for tenant IDs, custom API keys, or cookies.
API Docs Generation Guides
- The generator automatically creates documentation based on your MCP source
- Each tool becomes its own page;
inputSchemais expanded into a typed property tree - Each resource becomes its own page showing
uriandmimeType - Tools are grouped under "Tools", resources under "Resources"
- Required / deprecated / default / nullable / min / max metadata is rendered identically to OpenAPI
Composition
You can hand-author a markdown page that targets a single tool or resource by referencing its region in the page frontmatter:
Regions are written as tool:<name> or resource:<uri>. The mcp: frontmatter key uses the same <source>#<region> syntax as openapi: and graphql:.
RoadmapComing Soon
Support for prompts/list and stdio-transport MCP servers is currently in development.
MCP Samples
Learn how to setup MCP pages.
Show your support! Star us on GitHub ⭐️