> ## 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 end users. Each end user is a buyer with their own Sapiom key and saved cards.
> Use the buyer's key for every call made on that buyer's behalf. Never use one buyer's key for another user, and never give the agent the platform key.
> Agents call the hosted MCP tools at https://api.sapiom.ai/v1/mcp. Backends call the REST API at https://api.sapiom.ai/v1. Both take the key in an x-api-key header.
> Never ask a buyer for a card number, expiry date or CVV in chat. Buyers enter card details only on Sapiom's hosted pages.
> Follow the nextAction in each transaction result. Action links are secrets for the intended buyer only.
> Use one idempotencyKey per transaction. After a timeout, retry with the same key. Never start a new transaction to escape an uncertain outcome.
> Report an order as placed only when order.outcome is confirmed. If it is unknown, stop and hand off to a person.

# Connect the agent

> Open each buyer's MCP connection with that buyer'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`. The key you connect with decides which buyer the agent acts for, so each user's session needs its own connection with that user's buyer key.

## 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"),
    { 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 buyer, 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 \
  --header "x-api-key: $SAPIOM_BUYER_KEY"
```

Ask: **"List my Sapiom payment methods."** The agent calls `sapiom_list_payment_methods` and returns that buyer'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.