MCP servers

Storeware runs three Model Context Protocol servers on https://api.storeware.ai. Each answers streamable HTTP at one path for every shop: the credential says which shop.

ConnectingCopy Anchor Link

Point an MCP client at the endpoint. Each server is stateless: every message is one POST with a JSON-RPC body, no session is kept, and every tool answers in one round trip.

POST https://api.storeware.ai/mcp
Authorization: Bearer swa_...
Content-Type: application/json
MCP-Protocol-Version: <the version initialize settled on>

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

• The credential goes in the Authorization header and never in a tool's arguments, so it stays out of a model's context.
• initialize answers without a credential, so a client can learn what a server is before it signs in.
• A request that carries an Origin header is refused with 403. Agents are not browsers, and no web page may drive these servers.
• A protocol version the server does not know is answered 400 with the versions it does.

Signing inCopy Anchor Link

Every tool call needs a credential. A call without one, or with one that has ended, is answered 401 with a challenge a client can follow:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.storeware.ai/.well-known/oauth-protected-resource/mcp", scope="..."

There are three ways to hold a credential, and How an agent signs in covers each:

• A key pasted in. A merchant issues an agent key on the AI shoppers screen in the admin, or a merchant key under Settings, then Access keys.
• OAuth. /mcp and /admin/mcp are OAuth 2 protected resources. A client follows resource_metadata to the authorization server at https://api.storeware.ai/.well-known/oauth-authorization-server, which supports dynamic client registration, client ID metadata documents and PKCE with S256. A member of the shop's staff consents in the admin, and the token is bound to the one server named in resource. A token issued for /mcp is refused at /admin/mcp, and the other way round.
• Self registration. An agent registers itself and a person claims it with a six digit code.

/ucp/mcp is not part of this flow. A platform calls it with an agent key the merchant issued, and a shopper links their account through the shop's own identity linking.

The shopper server, /mcpCopy Anchor Link

For an agent shopping for somebody at one shop. The server's own instructions say how a purchase goes: search the catalogue, read a product to get a variant id, then create a checkout session with it. Prices and stock are read live.

• Finding things: search_products, get_product, compare_products, recommend_products, inventory_lookup and answer_shop_question. search_products returns the shop's reasoning as well as its results: see Answers.
• Buying: create_checkout_session, get_checkout_session, update_checkout_session, complete_checkout_session and cancel_checkout_session, the ACP checkout over MCP.
• After the sale: track_order and request_return. An agent key a shopper has linked also gets their orders and returns.
• Waiting for something: watch_for_it leaves an errand against one variant: when it is back in stock, or drops to a price you name, the errand completes. It never buys anything. list_watches, get_watch and cancel_watch follow it.

tools/list without a credential returns the tools every shop has. With a key it returns what that key may reach, including tools the shop's installed apps add.

The server also declares three MCP extensions:

A client that reads none of them gets the same tools and results.

The merchant server, /admin/mcpCopy Anchor Link

For a merchant working on their own shop from an agent: search and enrich products, check performance and search visibility, draft and revise pages, arrange menus, and apply proposals. Nothing is published or deleted from here. The merchant does both in the admin.

tools/list is empty until the caller has a credential, because the list describes the shop's back office. With one, the tools follow the key's permissions, and tools that change anything appear only when the merchant allowed changes. A background run is an MCP task: the tool that starts one returns its id, and tasks/get and tasks/cancel answer about it.

The UCP server, /ucp/mcpCopy Anchor Link

The MCP binding of the Universal Commerce Protocol, which every shop's profile at /.well-known/ucp names. Its tools are named and shaped by the protocol's own method list, such as search_catalog and create_checkout, which is why it is a separate server from /mcp. Every request carries the calling platform's profile in meta["ucp-agent"].profile. See UCP and ACP.

DiscoveryCopy Anchor Link

A client can read an MCP Server Card before it connects. Each names the server, its endpoint, its capabilities, and how it authenticates.

The name, version and capabilities on a card are the ones the server answers initialize with. Tools are listed as dynamic, because on two of the three servers they depend on who is asking.

Responses are signedCopy Anchor Link

Every response from the three servers is signed with RFC 9421 HTTP Message Signatures, ES256. Resolve the keyid against the keys in the shop's profile at /.well-known/ucp. Ignoring the signature changes nothing. See Answers.