AgentPOS for Alexa+

Turn any existing online store into an Alexa+ add-on with in-conversation checkout: MCP server, UCP checkout, merchant policies and verifiable receipts, with the store as merchant of record and no marketplace in between. The merchant chooses how to get paid.

Alexa+ for Builders is for Priceline. AgentPOS is for the corner store.

Status: in development for the Amazon "Build, Ship, Shape" Developer Hackathon 2026 (Alexa+ track, AWS Builder and Open Source mini challenges). Public from the first commit.

What this repository is

Amazon defines an Alexa+ add-on as "the bridge you deploy" between an MCP server and Alexa+. This repository is that bridge for stores that run AgentPOS: it sits in front of any AgentPOS store, consumes the store's public surfaces (MCP, REST API, /.well-known/ucp, checkout) and exposes the full Alexa+ contract:

• an MCP server (Streamable HTTP, spec 2025-11-25) with voice-ready item data and MCP Apps (product carousel, item card, order card, receipt card with a verified badge);

• the UCP-compatible checkout Alexa+ documents: /checkout-sessions create, get, update, complete and cancel, OAuth 2.0 bearer auth, 24-hour idempotency, 6-hour sessions, business errors as messages[];

• payment rails behind one interface, chosen by the merchant, never by us:

  1. the merchant's own PSP (Stripe, in test mode for the demo): the charge lands in the store's dashboard with the store as merchant of record;

  2. Amazon Wallet (com.amazon.payments.network_token, stored_payment_method): implemented against the published contract and exercised with a clearly labeled simulated PSP while the Alexa+ program is in preview;

  3. USDC on Stellar (org.x402.stellar) when the agent brings a wallet: real settlement through an open x402 facilitator;

• merchant-side agents on Amazon Bedrock AgentCore with Strands: onboarding (turns a URL into a voice-ready catalog and proposed policies; a human confirms), catalog (answers what a flat catalog cannot) and policy guardian (adds context to the store's deterministic policy and can hand the order to a human);

• a simulated Alexa+ client (apps/simulator), the official alternative path for the track: an Echo Show style web app, voice in and out, whose agentic client runs on Bedrock and drives the bridge end to end.

The store side (catalog, quotes, merchant policies, human approval queue, signed receipt chain, agent identity, settlement, WooCommerce order creation only after settlement) is AgentPOS itself. This bridge runs today against the public demo store at https://demo.agentposhq.com and needs nothing else.

Related MCP server: Maple Cart MCP

Layout

packages/store-client   typed client for the public surfaces of an AgentPOS store (discovery, REST, x402 challenge)
packages/fixture-store  test double of an AgentPOS Store: the real OpenAPI shapes, a bakery with physical goods, recorded demo responses
packages/bridge         the add-on: MCP server for Alexa+, MCP Apps views, UCP checkout sessions, payment rails, UCP profile
packages/agents         onboarding, catalog and policy guardian agents (Strands on AgentCore, Bedrock)
apps/simulator          simulated Alexa+ experience (Echo Show frame, host checkout pattern, inspection summary)
docs/                   strategy, submission draft, architecture, Alexa+ MCP design rules, security, AWS integration, usage events, friction log

Run

Requirements: Node >= 22.13 (uses node:sqlite unflagged, no native dependencies), pnpm 11+.

pnpm install
pnpm typecheck
pnpm test
pnpm dev:fixture-store # a bakery-shaped test double of an AgentPOS Store on :8790 (optional)
pnpm dev:bridge        # registers AGENTPOS_STORE_URL (default: the public demo store) and listens on :8787
pnpm dev:simulator     # the simulated Alexa+ experience on http://127.0.0.1:8788 (builds its web app first)

To run the bridge against the bakery instead of the public demo store, set AGENTPOS_STORE_URL=http://127.0.0.1:8790. The simulator needs the same BRIDGE_BEARER_TOKEN as the bridge: set it in .env for both, or copy the one-run token the bridge prints at boot when the variable is missing.

Environment variables are listed in .env.example; bash scripts/setup-wizard.sh walks a human through the ones only a human can create (AWS keys for Bedrock, model access, the Stripe test publishable key) and writes them to .env. Nothing in this repository ever holds a merchant's or a household's private key or PSP secret.

curl http://127.0.0.1:8787/health
curl http://127.0.0.1:8787/stores/demo-agentposhq-com/.well-known/ucp

The bridge

The bridge is multi-tenant: every Store it serves lives under /stores/{slug}/, and the first one is registered at boot from AGENTPOS_STORE_URL. Every response carries a Request-Id that is the trace id across the bridge's JSON logs, the Store request and the settlement.

MCP for Alexa+ at /stores/{slug}/mcp: Streamable HTTP, spec 2025-11-25, bearer auth. Six tools, one intent each: search_items, get_item, get_policies, start_checkout, get_order, get_receipt. Every result speaks first (a short text block) and carries structured content with prices as integer minor units; every failure is a typed error, never an empty result. Four tools carry an MCP Apps view (carousel, item card, order card, receipt card) that the bridge serves as a ui:// resource: one self-contained HTML file each, built from packages/bridge/apps/ with pnpm --filter @agentpos-alexa/bridge build:apps and committed, so nothing needs building to run.

UCP checkout at /stores/{slug}/checkout-sessions (create, get, update, complete, cancel), as Alexa+ documents it. Sessions are priced from the Store's catalog, quoted by the Store once a delivery address exists, and completed only when a payment rail reports settlement with a reference. Idempotency-Key is required on every state change and replayed for 24 hours; every response is validated in tests against the vendored official UCP schemas (packages/bridge/vendor/ucp). Platforms get bearer tokens from POST /oauth/token with client credentials (BRIDGE_OAUTH_CLIENT_ID and BRIDGE_OAUTH_CLIENT_SECRET).

Usage events: every tool call, rail call and model call lands in usage_events (docs/USAGE-EVENTS.md); pnpm --filter @agentpos-alexa/bridge usage:export writes the CSV and --summary the totals behind docs/COSTS.md.

The simulator

An Echo Show frame with the four display modes Amazon documents (inline, fullscreen, voice-only, hydrated), the Enabled add-ons the bridge serves, voice or text input, and an inspection summary per turn (.data/inspection-summary.json) that checks what Amazon's guide asks for: voice text first, three to five carousel items, first item within 500 ms, typed errors. Until the Household agent lands, a scripted router with no model maps the text to one Bridge tool, and the interface says so.

Checkout is the host's own pattern, as it is in Alexa+: when the customer confirms what to buy, the simulator opens a UCP checkout session on the bridge, fills the Demo household's synthetic address, shows the store's quote with the payment handlers the session accepts (the Amazon handlers, labeled SIMULATED), and completes with the chosen one. The order card and the receipt card that follow are the bridge's own MCP Apps views.

Principles we do not bend

• The store is merchant of record. No commission, no custody, no marketplace.

• The merchant chooses the rail. The bridge never holds a PSP key; the store executes the charge.

• Nothing scanned is published without human confirmation.

• No order is created without settled payment and a settlement reference.

• Every protocol detail (MCP, UCP, x402) lives behind an adapter and is pinned to a version.

• Amounts are integers in minor units. Never floats for money.

• Cryptography only through official SDKs (@x402/*, @stellar/stellar-sdk, MCP SDK).

• Simulated means labeled: in code, logs, responses and UI, and never switchable to a real PSP by configuration.

Strategy

Why the rails are ordered this way, why the simulator comes second and how impact is measured: docs/STRATEGY.md.

AWS integration

See docs/AWS-INTEGRATION.md (services, why each, where in the code).

Security by design

See docs/SECURITY.md.

Friction log

Written while building, one entry per obstacle with Amazon or AWS tooling: docs/FRICTION-LOG.md.

License

Apache-2.0. Copyright 2026 NovaCorpAI SpA.