Alexa+ MCP Authentication

Alexa+ supports a two-tier authentication model for MCP Add-ons:

Tier	Grant Type	Purpose	User Involved?
Tier 1	`client_credentials`	Service-level (M2M) authentication (if you have a private MCP Server)	❌ No
Tier 2	`authorization_code` + PKCE	User-level authentication & consent	✅ Yes

The Client Credentials Grant (grant_type=client_credentials) allows your MCP Add-on to authenticate at the service level — machine-to-machine (M2M) — without requiring any user interaction. This is the foundational authentication layer that must be established before user-level account linking occurs. When to Use Client Credentials

Initial service registration and health checks — Alexa+ validates your MCP server is reachable and authorized.
Fetching non-user-specific data — Catalogs, configurations, public content, service metadata.
Background sync operations — Periodic data refresh, cache warming.
Service-to-service API calls — Where no user context is needed.
Tool discovery and capability negotiation — MCP initialize and tools/list calls.

Authorization server metadata

Your authorization server metadata document must include client_credentials in the grant_types_supported array:

{
  "issuer": "https://auth.your-server.com",
  "authorization_endpoint": "https://auth.your-server.com/authorize",
  "token_endpoint": "https://auth.your-server.com/token",
  "response_types_supported": ["code"],
  "grant_types_supported": [
    "client_credentials",
    "authorization_code",
    "refresh_token"
  ],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["mcp:tools", "mcp:resources", "Your Defined Scopes"]
}

Client credentials token request

POST /token HTTP/1.1
Host: auth.your-server.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>

grant_type=client_credentials
&scope=mcp:service
&resource=https://your-server.com/mcp

Parameter Reference:

Parameter	Required	Description
grant_type	✅	Must be `client_credentials`
scope	✅	Service-level scope(s) requested (for example, mcp:service)
resource	✅	Canonical URI of the MCP server (prevents token misuse)
Authorization header	✅	HTTP Basic auth with client_id:client_secret (Base64 encoded)

Example Token Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "mcp:service"
}

Client credentials runtime flow

Step	Actor	Action
1	Alexa+	Initiates connection to MCP Add-on server
2	Alexa+	Checks for existing valid service-level access token
3	Alexa+	If no valid token → sends `POST /token with grant_type=client_credentials` to your authorization server.
4	Your authorization server	Validates client_id and client_secret
5	Your authorization server	If valid → issues access token with `mcp:tools`, `mcp:resource`, or self-defined scope
6	Alexa+	Stores service-level token (keyed by MCP Add-on)
7	Alexa+	Sends MCP requests (for example, `initialize`, `tools/list`) with Bearer token
8	Your MCP server	Validates Bearer token → processes request → returns response
9	Alexa+	On token expiry → repeats from Step 3 (no user interaction needed)

Scope separation model

Scope	Grant Type	Access Level	Example Operations
mcp:service	`client_credentials`	Service-level (no user context)	initialize, tools/list, catalog browsing, health checks
mcp:tools	`authorization_code`	User-level (user-specific)	Execute tools on behalf of user, personalized data
mcp:resources	`authorization_code`	User-level (user-specific)	Access user resources, subscriptions, preferences

Token endpoint requirements

Your token endpoint MUST do the following:

Accept grant_type=client_credentials in the request body.
Authenticate the client via HTTP Basic Authentication.
Validate the resource parameter matches the registered MCP server URI.
Issue a short-lived access token (3600 seconds or fewer recommended).
Return token_type: "Bearer" in the response.
Restrict issued scopes to service-level only (mcp:service). User-level scopes (mcp:tools, mcp:resources) are only issued via the authorization_code grant.

Your token endpoint MUST NOT:

Issue a refresh_token for client credentials grants.
Accept client credentials via query parameters. You must use the authorization header or POST body).

Error handling

HTTP Status	Error Code	Description
401	`invalid_client`	Client authentication failed (bad `client_id` or `client_secret`)
400	`invalid_scope`	Requested scope is not valid for client credentials grant
400	`invalid_request`	Missing required parameters
403	`access_denied`	Client is not authorized for the requested resource

Transition to user-level authentication

Once service-level authentication is established, the system transitions to user-level authentication only when a user-specific tool is invoked. For service-level operations (initialize, tools/list, catalog browsing), the service token is used with no user interaction required. For user-specific tools, the system initiates Tier 2 authorization_code + PKCE flow. For the complete implementation guide — including OAuth concepts, setup steps, linking patterns, and CLI configuration — see Account Linking for MCP Add-ons.

Pre-certification checklist (client credentials)

Auth server metadata includes client_credentials in grant_types_supported
Token endpoint accepts grant_type=client_credentials
Client authentication via HTTP Basic or POST body credentials
resource parameter validated against registered MCP server URI
Access token issued with mcp:service scope only
Token expires_in <= 3600 seconds
No refresh_token issued for client credentials grants
Error responses follow OAuth 2.0 error format (RFC 6749 Section 5.2)
Service-level token does NOT grant access to user-specific data

What isn’t supported

The following aren’t supported for MCP add-on authentication:

Dynamic Client Registration (DCR)
OpenID Connect (OIDC)
Step-Up Authorization
WWW-Authenticate headers in 401 responses

Get Started

Build with the MCP Toolkit

Build with the Category SDK

Testing

Certification

Reference

Authorization server metadata

Client credentials token request

Client credentials runtime flow

Scope separation model

Token endpoint requirements

Error handling

Transition to user-level authentication

Pre-certification checklist (client credentials)

What isn’t supported

​Authorization server metadata

​Client credentials token request

​Client credentials runtime flow

​Scope separation model

​Token endpoint requirements

​Error handling

​Transition to user-level authentication

​Pre-certification checklist (client credentials)

​What isn’t supported

​Related topics

Authorization server metadata

Client credentials token request

Client credentials runtime flow

Scope separation model

Token endpoint requirements

Error handling

Transition to user-level authentication

Pre-certification checklist (client credentials)

What isn’t supported

Related topics