Authentication

Who is calling the MCPServer’s endpoints: the credentials of a request, and the platform’s staff.

The public endpoint (/api/v1/mcp/smarter-project/) needs no credential, but serves its tools that write to GitHub only to a request that carries the caller’s GitHub token, from bearer_token(). The staff-only endpoint (/api/v1/mcp/smarter-operations/) serves only the platform’s staff (is_platform_staff()), whom it finds with acting_staff_user(), for a request that this platform signed for the person who is chatting with an LLMClient, or else with staff_user(), for a request whose api key is a staff user’s. views calls them before it reads a request’s JSON-RPC.

Note

Experimental. The MCPServer was designed and coded by Claude Code (Anthropic’s Claude Opus 5.5), with Lawrence McDaniel as co-author. It is experimental, and will be documented.

smarter.apps.mcpserver.protocol.auth.BEARER_SCHEME = 'bearer'

Bearer <token>, compared case insensitively.

Type:

The scheme of a GitHub token in an Authorization header

smarter.apps.mcpserver.protocol.auth.TOKEN_SCHEME = 'token'

Token <key>, compared case insensitively.

Type:

The scheme of a Smarter api key in an Authorization header

smarter.apps.mcpserver.protocol.auth.acting_staff_user(value)

Return the platform staff user of a signed X-Smarter-Acting-User header.

The platform sends this header to its own staff-only endpoint, for the user who is chatting with an LLMClient that has an MCPClient of it: see acting_user.

Side effects: one database query for the user, and one for their profile in the Smarter account.

Parameters:

value (str) – The header’s value.

Return type:

tuple[User | None, HTTPStatus]

Returns:

The user and 200 OK; None and 200 OK for a request that the platform signed for nobody in particular, which may list the tools but not call them; None and 401 Unauthorized if this platform did not sign the value, or it has expired; or None and 403 Forbidden if its user is not one of the platform’s staff, or no longer exists.

smarter.apps.mcpserver.protocol.auth.api_key(request)

Return the api key of a request’s Authorization: Token header.

This is the header that the Smarter api, and the smarter CLI, use for a SmarterAuthToken. The key is not checked here: see staff_user().

Parameters:

request (HttpRequest) – The request.

Return type:

str | None

Returns:

The key, or None if the request has none.

smarter.apps.mcpserver.protocol.auth.bearer_token(request)

Return the token of a request’s Authorization: Bearer header.

The MCPServer’s public endpoint serves its tools that write to GitHub, e.g. create_issue, to a request that carries the user’s GitHub token in this header. The token is wrapped in a SecretStr, so that it is never logged or shown by accident.

Parameters:

request (HttpRequest) – The request.

Return type:

SecretStr | None

Returns:

The token, or None if the request has no bearer token.

smarter.apps.mcpserver.protocol.auth.staff_user(request)

Return the platform staff user whose api key a request carries.

The key is checked with SmarterTokenAuthentication, the same check as the rest of the Smarter api, which reads the SmarterAuthToken from the database, refuses a key that is unknown or not active, and sends its authentication signals. Its user must be one of the platform’s staff, is_platform_staff(): the admin of another account is staff of that account only.

Parameters:

request (HttpRequest) – The request.

Return type:

tuple[User | None, HTTPStatus]

Returns:

The user and 200 OK, or None and 401 Unauthorized if the request has no valid, active api key, or None and 403 Forbidden if its user is not one of the platform’s staff.