Alexa+ MCP QuickStart Guide

​

MCP requirements for Alexa+

​

Technical requirements

• Your MCP server must support Streamable HTTP. The MCP specification (2025-11-25) deprecated the standalone HTTP+SSE transport in favor of Streamable HTTP. If your MCP server currently uses the legacy SSE transport, you must migrate before connecting to Alexa+.
• If you expect to provide visuals, follow the MCP Apps standard. The MCP Apps SDK (@modelcontextprotocol/ext-apps) provides Agent Skills that guide AI coding agents to scaffold a new MCP App with an interactive UI from scratch, or convert an existing OpenAI App to use MCP Apps.
• If you provide a text-only customer experience, proceed with existing server integration with Alexa+.
• Your MCP server must be accessible via a remote URL. During local development, you can use a tunneling service (such as cloudflared) to expose your server.

​

Authentication checklist

• Your MCP server returns 401 Unauthorized (without a WWW-Authenticate header) for unauthenticated requests.
• Your server hosts a Protected Resource Metadata (PRM) document at the well-known URI according to RFC 9728.
• Your auth server metadata is available at /.well-known/oauth-authorization-server.
• code_challenge_methods_supported must be present and must include S256. Account linking won’t proceed without it.

• Required: Use OAuth 2.1 authorization code flow with PKCE (S256).
• Required: Set the resource parameter to your MCP server’s canonical URI.
• Required: Include scopes from scopes_supported in the PRM document. Omit scope if scopes_supported is undefined.

• Required: Include the resource parameter.
• Required: Include the PKCE code_verifier.

• Required: Send the Bearer token in the Authorization header on every authenticated request.
• Required: Don’t send the Bearer token in the query string.

• Dynamic Client Registration (DCR)
• Client ID Metadata Documents (CIMD)
• OpenID Connect (OIDC)
• Step-Up Authorization.
• WWW-Authenticate header in 401 responses.

​

Performance

​

Security and data policies

​

Media (audio and video codecs)

• AAC LC, HE-AACv1, HE-AACv2 (enhanced AAC+), xHE-AAC, AAC ELD (enhanced low delay AAC), AMR-NB, AMR-WB, FLAC, MIDI, MP3, Opus, PCM/WAVE, Vorbis

• H.264/AVC, H.265/HEVC, AV1, VP9 / VP8, MPEG4, MPEG2, JPEG, VVC, LCEVC, WebP

​

Connect your MCP server to Alexa+

alexa-ai configure

• Path A: Add-on Agent Skill (recommended)
• Path B: Alexa AI CLI (manual)

​

Path A: Add-on Agent Skill (recommended)

I have an MCP server at https://mcp.example.com for a hotel booking service.

Help me create an Alexa+ add-on.

• MCP Introspection — Gets you authenticated with your developer account. Connects to your MCP server via JSON-RPC 2.0 (Streamable HTTP), discovers tools and resources, proposes an Add-on name. You confirm the name before proceeding.
• Add-on Scaffolding — Runs alexa-ai new mcp to create the project structure, fills in capability-derived descriptions (shortDescription, fullDescription, examplePhrases) derived from your MCP server. You review and approve.
• Media Assets & Compliance — Collects your privacy policy URL, terms of use URL, and required media assets (icon sizes + carousel image). Runs full validation.
• Deploy — Deploys your add-on to the development stage after you confirm. Returns your Add-on ID and enables testing in the web simulator.
• Submit — Submits your add-on for certification after you have tested your add-on in the web simulator.

​

Path B: Alexa AI CLI (manual)

alexa-ai new mcp --name "Hotel Finder" --locale en-US --mcp-server-url "https://mcp.example.com"

• shortDescription (≤123 characters)
• fullDescription (≤4000 characters)
• examplePhrases (3–4 phrases, each ≤200 characters)
• privacyAndCompliance.privacyPolicyUrl
• privacyAndCompliance.termsOfUseUrl
• mediaAssets (see addon.json schema reference below)

alexa-ai deploy

​

addon.json schema reference

{
  "manifestVersion": "1.0",
  "storeListing": {
    "distributionCountries": ["US"],
    "locales": {
      "en-US": {
        "default": "DEFAULT",
        "name": {
          "value": "Travel",
          "spokenForm": { "format": "ipa", "value": " " }
        },
        "shortDescription": "Search and book flights, hotels, and vacation packages",
        "fullDescription": "Search and book flights, hotels, and vacation packages. Compare prices across airlines and hotel chains. Book vacation packages.",
        "examplePhrases": [
          "Search hotels in Brisbane",
          "Search for flights from Seattle to Brisbane",
          "Find vacation packages to Hawaii"
        ],
        "privacyAndCompliance": {
          "privacyPolicyUrl": "https://example.com/privacy",
          "termsOfUseUrl": "https://example.com/terms"
        },
        "mediaAssets": {
          "icons": {
            "light": [
              { "size": "72x72", "uri": "https://example.com/icon-72x72.png" },
              { "size": "64x64", "uri": "https://example.com/icon-64x64.png" },
              { "size": "88x88", "uri": "https://example.com/icon-88x88.png" },
              { "size": "126x126", "uri": "https://example.com/icon-126x126.png" },
              { "size": "180x180", "uri": "https://example.com/icon-180x180.png" },
              { "size": "241x241", "uri": "https://example.com/icon-241x241.png" }
            ],
            "dark": []
          },
          "carouselImages": [
            { "uri": "https://example.com/carousel-1.png", "altText": "Hotel search results", "size": "600x900" }
          ],
          "bannerImages": []
        }
      }
    }
  },
  "integrations": [
    {
      "type": "MCP",
      "config": {
        "endpoints": {
          "default": {
            "type": "HTTPS",
            "uri": "https://mcp.example.com"
          }
        }
      }
    }
  ]
}

​

After onboarding

• Test your add-on using the web simulator or on a physical device (see Test Your MCP Add-ons).
• Make changes to addon.json and redeploy with alexa-ai deploy.
• Submit for certification when ready with alexa-ai submit.

​

Related topics

• Alexa+ MCP Overview
• Alexa+ MCP Client and App Lifecycle
• Alexa+ MCP Design Guide
• Test Your MCP Add-ons
• Authentication