> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sapiom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Sapiom Pay is for platforms whose agent shops for many users. Each user has their own Sapiom user key and saved cards.
> Use the user's key for every call made on that user's behalf. Never use one user's key for another user, and never give the agent the platform key.
> Backends call the REST API at https://api.sapiom.ai/v1. Agents can also call the hosted MCP tools at https://api.sapiom.ai/v1/mcp/pay. Both take the key in an x-api-key header.
> Keys that start with sk_test_ reach the sandbox, a separate environment with its own users and cards, at the same addresses. Use test card numbers only there.
> Never ask a user for a card number, expiry date or CVV in chat. Users enter card details only on Sapiom's hosted pages.
> Check the merchant before buying. Use purchase.type ucp_checkout only when the merchant check returns supported. Otherwise use browser_checkout.
> Follow the nextAction in each transaction result. Action links are secrets for the intended user only.
> Use one idempotency key per transaction. Resume an unanswered create with the same request and key. If a UCP update or cancellation is uncertain, stop and hand off to a person. If a browser cancellation is uncertain, read the transaction and resend the same cancellation, with the same key, only if it is not closed. Never start a new transaction to escape an uncertain outcome.
> For a ucp_checkout purchase, report an order as placed only when order.outcome is confirmed; if it is unknown, stop and hand off to a person. A browser_checkout purchase has no order confirmation (order is null): confirm the order on the merchant's page.

# Connect the agent

> Open each user's MCP connection with that user's key, and give your agent the rules it needs to pay safely.

Your agent reaches Sapiom's payment tools through a hosted MCP server at `https://api.sapiom.ai/v1/mcp/pay`. The key you connect with decides which user the agent acts for, so each user's session needs its own connection with that user's key.

The server takes the key in an `x-api-key` header, so your MCP client must be able to send one. It lists only the eight payment tools in [MCP tools](https://docs.sapiom.ai/api-reference/mcp-tools.md). Existing connections to `https://api.sapiom.ai/v1/mcp` keep working.

Browser checkout also needs a browser worker running [Browser Pay](https://docs.sapiom.ai/transactions/browser-pay).

## Connect in your agent's code

Open the connection when a session starts, with the key of the user you are serving. This example uses the TypeScript MCP SDK:

```typescript theme={null}
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

export async function connectSapiom(buyerKey: string) {
  const transport = new StreamableHTTPClientTransport(
    new URL("https://api.sapiom.ai/v1/mcp/pay"),
    { requestInit: { headers: { "x-api-key": buyerKey } } },
  );
  const client = new Client({ name: "your-agent", version: "1.0.0" });
  await client.connect(transport);
  return client;
}
```

Close the connection when the session ends. Never share one connection between users.

## Connect a client for testing

To try the tools by hand as one test user, add the server to a client such as Claude Code:

```bash theme={null}
claude mcp add --transport http sapiom https://api.sapiom.ai/v1/mcp/pay \
  --header "x-api-key: $SAPIOM_BUYER_KEY"
```

Ask: **"List my saved Sapiom cards."** The agent calls `sapiom_list_payment_methods` and returns that user's cards.

All tools are listed in the [MCP tools reference](https://docs.sapiom.ai/api-reference/mcp-tools.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.