xyd 0.1.0-beta - Coming Soon

API Pages
/
MCP

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; inputSchema is expanded into a typed property tree
  • Each resource becomes its own page showing uri and mimeType
  • 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.

Built with

Show your support! Star us on GitHub ⭐️