Skip to main content

Interface: McpRouterOptions

Defined in: index.ts:281

Options for configuring the MCP router

Properties​

aliases?​

optional aliases?: string[]

Defined in: index.ts:298

Additional HTTP paths where the MCP server is also mounted.

Useful when MCP clients differ in where they connect after OAuth: some follow the protected-resource resource metadata value as the endpoint, others always connect to the bare origin (/). Setting aliases: ['/'] serves both without requiring app-level path rewrites.

Example​

['/'] // also handle MCP requests at the bare root

apiBaseUrl?​

optional apiBaseUrl?: string

Defined in: index.ts:315

Base URL prepended to relative paths passed to apiCall (paths starting with /). Tool handlers can then call apiCall('GET', '/resource') without specifying a host.

Example​

'http://localhost:3000/api/v1'

auth?​

optional auth?: McpAuthOptions

Defined in: index.ts:377

OAuth / JWT authentication configuration for the MCP endpoint.

When set, incoming MCP requests must include a valid Bearer token in the Authorization header — except for publicMethods (by default initialize and tools/list), which bypass verification so clients can discover the server before authenticating. Invalid or missing tokens receive a 401 response with WWW-Authenticate: Bearer (or Bearer resource_metadata="..." when resourceMetadataUrl is set, per RFC 9728). Tokens that fail a requiredScopes check receive 403.

The verified token payload is accessible inside tool handlers via getIdentity. Fine-grained per-tool scope checks can be done with checkScopes.

Examples​

createMcpRouter(server, {
  auth: {
    cognitoUserPool: { userPoolId: 'us-east-1_xxx', clientId: 'yyy' },
    requiredScopes: ['mcp:access'],
  },
});
createMcpRouter(server, {
  auth: {
    verifyToken: async (token) => myJwtLib.verify(token),
  },
});

getApiHeaders?​

optional getApiHeaders?: (ctx) => Record<string, string>

Defined in: index.ts:341

Called once per incoming MCP HTTP request. Return a plain object whose key-value pairs will be merged into the headers of every apiCall made within that request's tool handlers.

Use this to forward any header from the MCP request — Bearer tokens, API keys, tenant IDs, trace headers, etc. — without coupling tool handlers to a specific authentication scheme.

Parameters​

ParameterType
ctxContext

Returns​

Record<string, string>

Examples​

getApiHeaders: (ctx) => ({ Authorization: ctx.headers.authorization ?? '' })
getApiHeaders: (ctx) => ({ 'x-api-key': ctx.headers['x-api-key'] as string })
getApiHeaders: () => ({ 'x-internal-key': process.env.INTERNAL_API_KEY! })

path?​

optional path?: string

Defined in: index.ts:286

The HTTP path where the MCP server will be mounted

Default​

'/mcp'

sessionIdGenerator?​

optional sessionIdGenerator?: () => string

Defined in: index.ts:306

Optional session ID generator for stateful MCP servers. When provided, a single shared transport is created and sessions are tracked. When undefined (default), the server operates in stateless mode where each HTTP request uses its own transport instance.

Returns​

string