MCP Authentication

The MCP endpoint supports multiple authentication modes:

Mode	Behavior
ROSTER_MCP_AUTH_MODE=api_key	Requires Authorization: Bearer <your-roster-api-key>.
ROSTER_MCP_AUTH_MODE=oauth	Requires a Roster OAuth access token with the /mcp audience.
ROSTER_MCP_AUTH_MODE=api_key,oauth	Accepts either API keys or OAuth bearer tokens.

Unset or blank defaults to api_key,oauth so API-key automation and OAuth MCP clients both work. Set oauth to disable API-key MCP access, or api_key to disable OAuth MCP access. Explicit none is local/dev only and is rejected in production.

API Keys

API-key MCP access uses bearer auth:

Authorization: Bearer <your-roster-api-key>

Individual tools enforce mcp:* scopes.

API-key scopes do not elevate the owner. Effective access is the key scopes intersected with the owning identity’s role, project access, and resource rules. The legacy all scope expands only the scope dimension.

OAuth

OAuth mode requires a Roster OAuth access token with the /mcp audience. OAuth consent offers project-resource write and label scopes only to admins and effective project owners. Platform administration scopes, such as mcp:team-members:write and mcp:platform-settings:write, are offered only to admins. Ordinary members can approve mcp:resolve and non-label read scopes, with tool execution still enforcing resource authorization. Relevant environment variables:

ROSTER_OAUTH_DYNAMIC_CLIENT_REGISTRATION
ROSTER_OAUTH_UNAUTHENTICATED_CLIENT_REGISTRATION
ROSTER_OAUTH_ACCESS_TOKEN_TTL_SECONDS
ROSTER_OAUTH_REFRESH_TOKEN_TTL_SECONDS
ROSTER_OAUTH_AUTH_CODE_TTL_SECONDS

Roster derives the MCP OAuth resource URI automatically as ${ROSTER_AUTH_URL}/mcp.

OAuth Client Registration

Production disables Dynamic Client Registration by default. Use a pre-registered public PKCE client when the MCP client or workspace supplies a client ID.

If an MCP client must self-register, restrict the registration endpoint to the administrator/client network at the ingress and temporarily set:

ROSTER_OAUTH_DYNAMIC_CLIENT_REGISTRATION=true
ROSTER_OAUTH_UNAUTHENTICATED_CLIENT_REGISTRATION=true

Complete the client connection once, then remove both variables (or set them to false) and restart Roster. The registration remains in the database. Do not leave unauthenticated registration enabled on an unrestricted public deployment.