# MCP servers

> The three Model Context Protocol servers, how to connect to each, and how a client authenticates.

Source: https://storeware.ai/docs/agents/mcp

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

| Endpoint | Server name | For | Credential |
| --- | --- | --- | --- |
| `https://api.storeware.ai/mcp` | `storeware` | An agent shopping for somebody | An agent key (`swa_`) |
| `https://api.storeware.ai/admin/mcp` | `storeware-admin` | A merchant running their shop from an agent | A merchant key (`swm_`) |
| `https://api.storeware.ai/ucp/mcp` | `storeware-ucp` | A platform speaking the Universal Commerce Protocol | An agent key (`swa_`) |

## Connecting

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.

```http
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 in

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
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](https://storeware.ai/docs/agents/agent-auth) 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](https://storeware.ai/docs/agents/ucp-acp#identity-linking).

## The shopper server, `/mcp`

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](https://storeware.ai/docs/agents/answers).
- **Buying:** `create_checkout_session`, `get_checkout_session`, `update_checkout_session`, `complete_checkout_session` and `cancel_checkout_session`, the [ACP](https://storeware.ai/docs/agents/ucp-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:

| Extension | What it serves |
| --- | --- |
| `io.modelcontextprotocol/ui` | Views of an answer and an order, as `ui://` resources a host can draw beside the conversation. A tool names its view in `_meta.ui.resourceUri`. |
| `io.modelcontextprotocol/tasks` | An errand, as a task whose id is the errand's id. `tasks/get` and `tasks/cancel` answer about it. |
| `io.modelcontextprotocol/skills` | The shop's own `shop-here` skill, at `skill://shop-here/SKILL.md`, for the shop the key names. |

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

## The merchant server, `/admin/mcp`

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/mcp`

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](https://storeware.ai/docs/agents/ucp-acp).

## Discovery

A client can read an [MCP Server Card](https://static.modelcontextprotocol.io/schemas/mcp-server-card/v1.json) before it connects. Each names the server, its endpoint, its capabilities, and how it authenticates.

| Card | Describes |
| --- | --- |
| [`https://storeware.ai/.well-known/mcp/server-card.json`](https://storeware.ai/.well-known/mcp/server-card.json) | The merchant server, `/admin/mcp`. |
| `https://<shop>/.well-known/mcp/server-card.json` | That shop's UCP server, `/ucp/mcp`, titled with the shop's name. |

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 signed

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](https://storeware.ai/docs/agents/answers#verifying-what-you-were-told).