mcp_auth

build_auth turns MCP_AUTH_TOKEN and the route-bound MCP_ROUTE_TOKENS into the bearer-token verifier the HTTP transport enforces.

See also

Configuration and HTTP transport

Optional bearer-token authentication for the HTTP transport.

The stdio transport is a local, single-client channel and needs no authentication. When the server is exposed over HTTP (containers, remote deployments, shared hosts) an operator can set MCP_AUTH_TOKEN to require a bearer token: FastMCP then validates the Authorization header before any MCP request is served. Without the setting the server behaves exactly as before, so this stays opt-in and backward compatible.

MCP_AUTH_TOKEN keeps its original meaning: one static token whose client id is CLIENT_ID. MCP_ROUTE_TOKENS adds route-bound tokens on top – a JSON object ({“<route>”: “<token>”}, since pydantic-settings parses list/dict values as JSON only). A route token authenticates as its route and is rejected when the same request declares a different route through the routing headers. Both settings may be combined: the static token never takes part in route checking, so its semantics are unchanged. When neither is configured, build_auth() returns None and no auth middleware is installed.

Route mismatch is handled in this module, in the single place that sees both the presented token and the request headers. A mismatch makes the verifier return None, which the bearer middleware turns into 401 with a WWW-Authenticate challenge; the two routes are recorded with logger.warning so the rejection stays auditable. Nothing is raised here on purpose: an exception from a verifier surfaces as a 500 instead of a clean authentication failure. A request without a usable declared route (no routing header, or a header that sanitises to unknown) is accepted and attributed to the token’s own route; only two different, both-present routes fail closed.

novelai_image_mcp.mcp_auth.CLIENT_ID = 'novelai-image-mcp'

Identity reported to the server for the single configured token.

class novelai_image_mcp.mcp_auth.RouteTokenVerifier(tokens, *, routes, settings)

Bases: StaticTokenVerifier

Static tokens, plus fail-closed route checking for route-bound tokens.

Tokens registered in route_tokens must not disagree with the route the request declares through the routing headers; every other token (the static MCP_AUTH_TOKEN) is returned untouched, exactly as before.

Parameters:

• tokens (dict[str, dict[str, Any]])

• routes (Mapping[str, str])

• settings (MCPServerSettings)

async verify_token(token)

Return the token’s access rights, or None to reject the request.

Parameters:

token (str)

Return type:

AccessToken | None

novelai_image_mcp.mcp_auth.build_auth(settings)

Return a bearer-token verifier, or None when auth is not configured.

StaticTokenVerifier compares the presented token against a fixed mapping; it is the documented FastMCP pattern for operator-managed static tokens. Rotate the token by changing MCP_AUTH_TOKEN and restarting.

MCP_ROUTE_TOKENS entries are merged into the same mapping, each with client_id set to its route, and additionally checked against the route the request declares (see RouteTokenVerifier). With no MCP_AUTH_TOKEN and no usable route token the function returns None, which leaves the transport exactly as it is today.

Parameters:

settings (MCPServerSettings)

Return type:

TokenVerifier | None