MCP overview

What is MCP?

Overview

MCP connects AI apps to tools and data.

Aly exposes workspace tools through that standard.

Claude, Cursor, Codex, and internal agents can use it.

Official standard

Read the official MCP specification.

MCP connects AI apps to external systems.

Aly targets 2025-11-25.

It uses JSON-RPC 2.0.

Stateful sessions are enabled.

Capability negotiation is enabled.

Aly support

Aly ships Streamable HTTP MCP.

Tool calls are request/response today.

Bearer auth is scoped.

OAuth protected-resource metadata is published.

Tools cover commerce, media, analytics, and webhooks.

Voice, settings, UCP, and A2A are included.

Get started

Create an Aly API key or OAuth token.

Point the client at https://aly.store/api/mcp.

Start with Claude Desktop or Cursor.

When to use MCP

Use MCP when an agent needs tools to operate an Aly workspace.
Use UCP when a buyer agent needs catalog, cart, quote, or checkout data.
Use A2A when another agent needs to delegate a multi-turn task to a store agent.

Start here

Use this path when you want an agent to operate an Aly workspace through MCP.

Choose a credential
Use an aly_* API key for an owner-issued integration, or an aly_oauth_* OAuth token when a user installs your integration into their workspace. See OAuth + bearer tokens.
Connect a client
Add https://aly.store/api/mcp to Claude Desktop, Cursor, or another MCP client that supports streamable HTTP.
Inspect the tools
Use the client's MCP tool inspector or the Tools reference to confirm the tool list and required scopes before giving an agent write access.

At a glance


Endpoint	`POST https://aly.store/api/mcp`
Transport	MCP Streamable HTTP over JSON-RPC 2.0; Aly tools return request/response JSON today
Auth	Bearer token — `aly_` API key or `aly_oauth_` OAuth token
OAuth metadata	`GET /.well-known/oauth-protected-resource`
Session header	`Mcp-Session-Id` is accepted when issued by the MCP client session
Server push	Disabled today; Aly MCP tools are request/response and do not send unsolicited events
Discovery version	`2025-11-25`
Tool count	~80 tools across 23 families
Rate limit	Per-principal durable bucket; per-IP pre-auth bucket

Before you begin

Browser session cookies and Convex Auth session JWTs are not MCP credentials.
Give agents the smallest scope set that covers the job they need to do.
Use a real MCP client for day-to-day work; use curl only for smoke tests and debugging.

Trust model

Aly verifies the bearer token, resolves its workspace, and checks each tool against the token's scopes before running server-side code.
Browser-originated MCP requests must pass Aly's origin policy; non-browser clients usually send no Origin header.
The MCP client remains responsible for showing tool requests to the user and collecting any human approval before it sends a tool call.
Aly validates tool arguments on the server and rate-limits both pre-auth and post-auth traffic.

Operator vs storefront scopes

Most MCP integrations want operator-mode scopes because they act on a merchant workspace. Storefront-mode scopes are narrower — they let an agent read public catalog data without seeing customer or order records. See Operator vs storefront scopes.

First request

MCP clients negotiate capabilities over JSON-RPC. A minimal initialize request looks like this:

1curl -X POST https://aly.store/api/mcp \2  -H "Authorization: Bearer aly_..." \3  -H "Accept: application/json, text/event-stream" \4  -H "Content-Type: application/json" \5  -H "MCP-Protocol-Version: 2025-11-25" \6  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"manual","version":"0.1"}}}'

A successful session can then call tools/list and tools/call. In normal use, Claude Desktop, Cursor, Codex, or another client handles this handshake for you.

Verify the connection

The client should show an Aly MCP server named aly-store-mcp.
The tool inspector should list Aly tools with JSON Schema input definitions.
A 401 means the token is missing or invalid; a 403 means the token is valid but missing a required scope.

Tool families

Tools are grouped by feature area. Each family ships as its own module on the server, and the live JSON Schema input specs are exposed through tools/list.

Family	What it does	Typical scopes
a2a	Inspect agent tasks running on your sites	`read:sites`
analytics	Site traffic, conversion, activity feed	`read:analytics`
api-keys	Mint, list, revoke API keys	`manage:api_keys`
cms	Pages and structured CMS blocks	`read:content`, `write:content`
collections	Manual and rule-based product groupings	`read:content`, `write:content`
commerce-ops	Fulfillment, returns, exchanges	`write:orders`
content	Top-level site content and theme	`read:content`, `write:content`
coupons	Discount codes and usage caps	`read:content`, `write:content`
customer-groups	Segments for pricing and gated content	`read:customers`, `write:customers`
customers	Buyer profiles and order history	`read:customers`, `write:customers`
domains	Custom-domain attach + verification	`manage:domains`
galleries	Product galleries and image grids	`read:media`, `write:media`
media	R2-backed asset CRUD	`read:media`, `write:media`
memberships	Subscription tiers and subscribers	`read:content`, `write:content`
orders	Order list, detail, mutation	`read:orders`, `write:orders`
price-lists	Dynamic pricing per customer group	`read:content`, `write:content`
sites	Site CRUD, publish, theme settings	`read:sites`, `write:sites`, `delete:sites`
ucp	UCP-shaped catalog + checkout from MCP	`read:content`
voice	Voice agent configuration and prompts	`manage:voice`
webhooks	Endpoint registration and delivery log	`read:sites`, `write:sites`
workspace	Workspace settings	`manage:workspace`

For the full per-tool reference see Tools reference.

Errors and idempotency

Tool calls return JSON-RPC errors with a stable code and a descriptive message. State-changing tools that take anidempotency_key in their input dedupe retries on that key for ~24 hours.

Discovery

The platform's capability surface is also published at GET /.well-known/protocols — an MCP-aware client can bootstrap from there to find the MCP endpoint, OAuth metadata, UCP catalog, A2A agent card, and OpenAPI spec in one request.

Next steps

Connect Claude Desktop — add Aly to Claude's MCP config.
Connect Cursor — use Aly tools from Cursor's agent.
OAuth + bearer tokens — choose the right credential model.
Tools reference — review tool families, schemas, and scopes.

Was this page helpful?