Transports

For the complete documentation index, see llms.txt. Markdown variants of every page are available by appending .md to the URL.

HTTP transport

xmcp servers speak both current MCP protocol generations over Streamable HTTP: requests carrying the 2026-07-28 per-request _meta envelope (including server/discover) are served natively, and 2025-era clients that start with the classic initialize handshake are served through the stateless fallback. Both paths build a fresh server per request — no session state survives between requests.

The http configuration customizes the HTTP server. Set it to true to use defaults, or provide an object to override specific options:

const config: XmcpConfig = {
  http: {
    port: 3001,
    host: "127.0.0.1",
    endpoint: "/mcp",
    bodySizeLimit: 10485760, // 10MB
    debug: false, // adds extra logging to the console
  },
};

export default config;

These are the default values. Override only what you need to customize.

Subscription streams

Clients using protocol revision 2026-07-28 can open a subscriptions/listen stream for list-changed notifications. When the server supports the requested notifications, the stream stays open until the client disconnects or the handler closes it. Keepalive frames do not impose a stream lifetime limit.

http.maxSubscriptions accepts a nonnegative integer and limits concurrent subscription streams per HTTP handler instance. Each process, worker isolate, or serverless instance has its own limit; this is not a deployment-wide quota. Omitting the option preserves the MCP SDK's default. Set it to 0 to refuse all subscription streams:

import type { XmcpConfig } from "xmcp";

const config: XmcpConfig = {
  http: {
    maxSubscriptions: 0,
  },
};

export default config;

The option applies to standalone HTTP, Vercel, Cloudflare, and the Express, Fastify, NestJS, Next.js, Hono, and SvelteKit adapters. It does not change STDIO or disable SSE used by ordinary tool calls and progress notifications.

When the cap is reached, the SDK returns HTTP 200 with JSON-RPC error -32603, Subscription limit reached, before acknowledging the subscription. A positive limit bounds the number of streams, not how long an accepted stream stays open. Closing a stream frees its slot.

For a server with a fixed component roster on a platform with request duration limits, consider disabling subscriptions to avoid holding an invocation open. Clients must request lists again as needed instead of relying on notifications. Those list requests still execute normally and consume resources. The setting does not change the server's advertised listChanged capabilities.

The HTTP transport example sets the limit to 0 and includes a runnable request demonstrating the refusal.

CORS

CORS (Cross-Origin Resource Sharing) middleware that can be configured to control cross-origin requests.

const config: XmcpConfig = {
  http: {
    cors: {
      origin: "*",
      methods: ["GET", "POST"],
      allowedHeaders: [
        "Content-Type",
        "Authorization",
        "mcp-session-id",
        "mcp-protocol-version",
        "mcp-method",
        "mcp-name",
        "x-mcp-client-name",
        "x-mcp-client-version",
        "x-mcp-client-title",
        "x-mcp-client-website-url",
        "x-mcp-client-description",
      ],
      exposedHeaders: ["Content-Type", "Authorization", "mcp-session-id"],
      credentials: false,
      maxAge: 86400,
    },
  },
};

export default config;

STDIO transport

The stdio configuration customizes the STDIO transport. Set it to true to use defaults, or provide an object to override specific options:

By default you enable STDIO transport by setting it to true.

const config: XmcpConfig = {
  stdio: true,
};

You can also customize the debug mode and this would enable it as well.

const config: XmcpConfig = {
  stdio: {
    debug: false, // adds extra logging to the console
  },
};

Silent mode

When using STDIO transport, any console.log, console.debug, console.info, console.warn, or console.error calls in your tool handlers will write to stdout, which interferes with the MCP protocol. Enable silent to automatically redirect all console output to stderr instead:

const config: XmcpConfig = {
  stdio: {
    silent: true,
  },
};

This is useful when your tools or dependencies contain debug logs that would otherwise corrupt the MCP communication. The logs are not lost, they are still visible in stderr.

Troubleshooting

Keep in mind that clients like Claude Desktop are not compatible with STDIO logging and would cause a JSON parsing error. You can use the silent option to redirect console output to stderr and avoid this issue.