Alexa+ MCP Authentication

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

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:

{
  "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:

Example Token Response:

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

Client credentials runtime flow

Scope separation model

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

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

Related topics

• Account Linking
• Overview
• Create an MCP Add-on
• Alexa+ MCP Client and App Lifecycle
• Alexa+ MCP Design Guide

Last updated: Jul 10, 2026