MCP ServerAlpha
Serve an API document as an MCP server, over HTTP or stdio
@xyd-js/mcp-server turns an OpenAPI document into an MCP server:
one tool per operation, which calls your API when an agent uses it.
- tool names are the
operationIds, verbatim (listPets,getPet) - inputs are one flat JSON Schema per tool: the path, query and JSON-body properties side by side
(
--groupednests them underpathParams,queryParams,headers,cookiesandrequestBody) - annotations say what a tool does:
readOnlyHintforGET,HEAD,OPTIONSandTRACE,destructiveHintforDELETE,PUTandPATCH,idempotentHintfor the read-only methods,PUTandDELETE - an operation that only takes a form, multipart or binary body is left out (a tool sends JSON)
- calls send the caller's bearer,
Accept: application/jsonand your extra headers, and answer the response body; a non-2xx answer is a tool error with the status and the start of the body - resources: one markdown page per operation (
api-reference://<name>), linked from each answer
Quickstart
The document may be a path or a URL. The API is called at the document's first servers entry;
--base-url points the tools elsewhere.
Modes
The default. Streamable HTTP with sessions: initialize opens one (Mcp-Session-Id), answers may
stream as server-sent events, and GET / DELETE work on the session. Sessions live in memory:
one idle for --session-idle-timeout seconds (default 1800) is closed, and beyond --max-sessions
(default 1000) an initialize answers 503. Every request of a session has to reach the same
instance, so for a remote deployment use the stateless mode.
Authentication
The server keeps no credentials of its own.
- HTTP: every request's
Authorization: Bearer <token>is sent on by the tool calls of that request — read on every request, not only oninitialize, and stored nowhere. A request without one calls the API without one, and the API answers for itself (e.g.401, returned as a tool error). - stdio: the bearer is read from
XYD_API_TOKEN(--token-env <NAME>names another variable); stderr says which variable it came from, or warns when it is not set.
Host check
A local server could be reached from a web page through DNS rebinding, so the HTTP server accepts
only the Host names localhost, 127.0.0.1 and [::1] by default. Name the hosts it is reached
by, or turn the check off when a proxy in front of it checks the host:
Options
| Option | |
|---|---|
--port <n> | the port (default $PORT, else 3000) |
--host <host> | the interface to listen on (default: all) |
--path <path> | a mount path, repeatable or comma-separated (default /mcp) |
--stateless | the stateless HTTP mode |
--session-idle-timeout <seconds> | sessions mode: close a session idle this long (default 1800; 0 keeps them) |
--max-sessions <n> | sessions mode: the most open sessions (default 1000) |
--allowed-hosts <names> | more accepted Host names, comma-separated (a port is ignored) |
--disable-host-check | accept any Host |
--token-env <NAME> | stdio: the variable holding the API bearer (default XYD_API_TOKEN) |
--base-url <url> | the API base URL (default: the document's first server) |
--header "Name: value" | a header on every API call, e.g. an API version header; repeatable |
--read-only | only the read-only tools ( GET, HEAD, OPTIONS, TRACE) |
--tools <names> | only these tools, comma-separated |
--limit-cap <n> | cap an integer limit parameter at n (its maximum, and the calls clamp to it) |
--max-bytes <n> | cut answers after n bytes, with a marker saying so (default 262144) |
--grouped | grouped tool inputs instead of flat ones |
--skip-resources | no markdown resources (they render with the xyd API reference components) |
--name <name> | the server name answered in initialize |
A second positional argument takes llms.txt URLs: their pages become a search tool (it needs
OPENAI_API_KEY for the embeddings).
Client Configuration
Library
The CLI is a thin layer over two packages.
@xyd-js/mcp generates the tools (through uniformToMcpTools of @xyd-js/uniform) and registers
them on an McpServer of the MCP TypeScript SDK:
tools is plain JSON (each tool keeps its HTTP binding), so it can be generated at build time and
loaded from a file. @xyd-js/mcp-server adds the transports: prepareMcpServer(options) reads the
sources once, createMcpHttpApp(prepared, { stateless, paths, allowedHosts }) returns an Express app,
and serveMcpStdio(prepared) serves stdio.
Documenting an MCP Server
xyd can document any streamable-HTTP MCP server, this one included: point
api.mcp at its URL. The docs build sends initialize, keeps the session the server
issues and reads answers sent as JSON or as an event stream.
Show your support! Star us on GitHub ⭐️