basalt / mcp/src / McpRoutesOptions

Interface: McpRoutesOptions

Properties

allowedOrigins?

> optional allowedOrigins?: readonly string[] | "*"

Origins (scheme + host + port, e.g. https://app.example.com) allowed to call the endpoint from a browser. A request carrying an Origin header that is neither same-origin (its host equals the request's Host) nor listed is refused with 403 — the MCP Streamable-HTTP spec requires validating Origin (anti DNS-rebinding / CSRF). Requests without Origin (non-browser MCP clients) are unaffected. '*' disables the check.

auth?

> optional auth?: boolean

Defined in: mcp/src/server.ts:188

Require an authenticated caller for the endpoint itself (sets the route's meta.auth, enforced by authPlugin). Without it initialize and tools/list are anonymous — tool CALLS still run each route's own guards.

listVisibleOnly?

> optional listVisibleOnly?: boolean

Defined in: mcp/src/server.ts:209

Hide from tools/list the tools the caller statically cannot use. Default true. Only side-effect-free checks run (never the guards — those consume rate limits and write audit/denial records):

meta.auth tools are hidden from a caller with no ctx().user (when authPlugin — a guard claiming auth — is registered);
any key whose plugin registered a pure visibility check in http:route-visibility — teamsPlugin hides meta.teamRole tools from callers who do not hold the role in the current tenant, permissionsPlugin hides meta.can tools whose permission(s) the caller does not hold.

NOT filtered (listed, refused on call): every other guarded key — mfa, scopes, subscribed/feature, audiences, rate limits and any check made inside a handler. Visibility is never authorization: tools/call still runs every guard.

meta?

> optional meta?: Record<string, unknown>

Defined in: mcp/src/server.ts:190

Extra meta for the /mcp route (e.g. { can: 'mcp:use' }).

path?

> optional path?: string

Defined in: mcp/src/server.ts:164

Endpoint path. Default /mcp.

rateLimit?

> optional rateLimit?: object

Defined in: mcp/src/server.ts:173

Rate-limit budget for the /mcp endpoint, applied as the route's meta.rateLimit (enforced by securityPlugin in a dedicated bucket). Recommended for exposed deployments: tool calls are often heavier than plain endpoints. A tool route's OWN meta.rateLimit also applies when it is invoked as a tool through /mcp (securityPlugin enforces it as a route guard), keyed by the /mcp caller's ip, which the tool request inherits.

limit

> limit: number

windowMs

> windowMs: number

sessions?

> optional sessions?: false | McpSessionOptions

Defined in: mcp/src/server.ts:222

Streamable-HTTP sessions (default: on). A successful initialize answers with an Mcp-Session-Id header; every later POST must carry it (400 without it; 404 for an unknown, expired or foreign one — the client then re-initializes) and DELETE with it ends the session. A session is bound to the caller that opened it (ctx().user + tenant, or — anonymous — a hash of the Authorization/x-api-key credentials), so a notifications/cancelled in a later POST of the SAME session cancels the call it names, while no other session can. Sessions live in this process's memory: behind several replicas use sticky sessions, or false to run stateless (each POST its own session; no cross-POST cancellation).