Transports | xmcp

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:

xmcp.config.ts

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.

CORS

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

xmcp.config.ts

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.

xmcp.config.ts

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

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

xmcp.config.ts

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:

xmcp.config.ts

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.