Authentication for Category MCP Add-ons

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

1. Initial service registration and health checks — Alexa+ validates your MCP server is reachable and authorized.
2. Fetching non-user-specific data — Catalogs, configurations, public content, service metadata.
3. Background sync operations — Periodic data refresh, cache warming.
4. Service-to-service API calls — Where no user context is needed.
5. 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:

Client credentials token request

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:

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:

1. Accept grant_type=client_credentials in the request body.
2. Authenticate the client via HTTP Basic Authentication.
3. Validate the resource parameter matches the registered MCP server URI.
4. Issue a short-lived access token (3600 seconds or fewer recommended).
5. Return token_type: "Bearer" in the response.
6. 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:

1. Dynamic Client Registration (DCR)
2. OpenID Connect (OIDC)
3. Step-Up Authorization
4. WWW-Authenticate headers in 401 responses

---

---

Last updated: Jul 16, 2026