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

> ## Agent Instructions
> Agentcard is for companies whose agent buys for their users. Pick one path: the opencommerce SDK (@agent-cards/commerce-sdk) gives your agent one buy tool that finds the product, builds the cart, gets the user's approval and places the order at real stores; the Agentcard SDK (@agent-cards/sdk) pays with the user's own card when your agent already shops in a browser (Browser Use, Kernel, Browserbase, Anchor or Notte); the Purchase API (POST /buy) does the same purchase flow over plain HTTP in any language; Issuing gives the agent its own card.
> Start with `npx agent-cards init` in the app's folder (Node 22 or later). No invite is needed: it creates your Agentcard account if you don't have one, installs the opencommerce SDK and puts the credentials in the env file, kept out of git. From a coding agent, run `npx agent-cards init --print --categories all --implementation tool --wallet vault --skip-install` to get the setup steps to apply yourself.
> Vault is by invitation: request it at https://agentcard.com/get-started?utm_source=docs&utm_medium=llms&utm_campaign=agent-instructions. opencommerce needs no invite.
> Never ask a user for a card number, expiry date or CVV in chat. Send them the Vault link; they add their card on Agentcard's page, and the agent never sees the number.
> Every purchase is approved by the user, with a passkey or Face ID, or by an auto-approval they granted. An approval covers one merchant and one exact total. If the total changes, ask again. When a result says the user already said yes, don't ask again.
> `init` writes PRODUCTION credentials, which place real orders, so test in sandbox first. For opencommerce, run `npx agent-cards credentials --mode sandbox` and put the two lines it prints in place of the production ones in the env file `init` wrote, because that command only prints them; sandbox then runs the whole flow against real stores and stops before payment, so no order is placed and nobody is charged. For Vault and Issuing, sandbox credentials issue test cards that no real merchant accepts; try the checkout against shop.agentcard.sh, a test store on Stripe test mode.
> Tell the user an order is placed only after Agentcard reports it placed.
> Vault is free up to 5,000 users (https://agentcard.com/pricing). opencommerce takes 1% of each completed order. Full docs in one file: https://docs.agentcard.com/llms-full.txt

# Connect to the Commerce MCP server

> Point your agent at https://mcp.opencommerce.sh/mcp with your credentials, set the shopper and chat ids, and make a first buy call in the sandbox.

Connect your agent to one URL, `https://mcp.opencommerce.sh/mcp`, and it can search stores, build carts, get each shopper's approval and place orders for your shoppers. You install no SDK. No model runs on the server: your agent calls the tools, and Agentcard does the shopping.

The server speaks Streamable HTTP and keeps no session: every request carries its own credentials. If your agent runs in TypeScript and you want to control each reply and link, use the [Commerce SDK](https://docs.agentcard.com/commerce-sdk/quickstart.md). For plain HTTP from any language, see [Make your first purchase over HTTP](https://docs.agentcard.com/purchase-api/http.md).

## Get your credentials

The server takes the same credentials as the Commerce SDK: a client ID and a client secret. Sign in with the Agentcard CLI, where a new email creates your account, and copy your sandbox credentials:

```bash theme={null}
npx agent-cards signin
npx agent-cards credentials --mode sandbox
```

Sandbox credentials reach the sandbox, Agentcard's test mode, where stores decline at checkout and nothing is charged. Production credentials place real orders. You switch by changing the credentials alone: the URL and the tools stay the same. Keep the client secret on your server, never in a browser, a mobile app or a prompt, because anyone who holds it can shop as your company.

## Connect a client

Send the credentials in the `Authorization` header, as `Bearer <YOUR_CLIENT_ID>:<YOUR_CLIENT_SECRET>`, or as `Basic` with the base64 of `<YOUR_CLIENT_ID>:<YOUR_CLIENT_SECRET>`. A request with missing or refused credentials gets `401`. The examples read the credentials from `AGENTCARD_CLIENT_ID` and `AGENTCARD_CLIENT_SECRET`, so no secret lands in a file you commit.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http agentcard-commerce https://mcp.opencommerce.sh/mcp \
>   --header "Authorization: Bearer $AGENTCARD_CLIENT_ID:$AGENTCARD_CLIENT_SECRET"
> ```
>
> Run `claude mcp list`. The server shows as connected once Agentcard accepts the header.

> [tab] Cursor
>
> Add the server to `.cursor/mcp.json`, and set both variables in your shell profile before you start Cursor:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "agentcard-commerce": {
>       "url": "https://mcp.opencommerce.sh/mcp",
>       "headers": { "Authorization": "Bearer ${env:AGENTCARD_CLIENT_ID}:${env:AGENTCARD_CLIENT_SECRET}" }
>     }
>   }
> }
> ```

> [tab] AI SDK
>
> Run `npm install ai @ai-sdk/mcp zod`, then build the client as [Set the shopper and chat ids](#set-the-shopper-and-chat-ids) shows.

> [tab] Other MCP clients
>
> Any client that speaks Streamable HTTP and sends a fixed request header works. To test from a terminal, list the tools:
>
> ```bash theme={null}
> curl -s -X POST https://mcp.opencommerce.sh/mcp \
>   -H "Authorization: Bearer $AGENTCARD_CLIENT_ID:$AGENTCARD_CLIENT_SECRET" \
>   -H "Content-Type: application/json" \
>   -H "Accept: application/json, text/event-stream" \
>   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
> ```

ChatGPT can't connect yet: its custom connectors send no fixed `Authorization` header, and the server has no OAuth sign-in. Claude's custom connectors on claude.ai and Claude Desktop take the header, but with no server of yours in between, the model picks the shopper and chat ids, so use them to try the server and not to serve shoppers.

## Set the shopper and chat ids

Every tool that acts for a shopper takes two ids that you own. `shopper_id` is your own id for the person, the same on every call for that person and different for every person. `thread_id` is your id for the chat, and Agentcard keeps one open purchase for each shopper and chat.

Fill both in on your server, never in the model. A model that invents `shopper_id` can send one shopper's cart to another. With the AI SDK, wrap each tool so your ids overwrite whatever the model sent:

```ts agentcard-mcp.ts theme={null}
import { createMCPClient } from '@ai-sdk/mcp';

export const mcp = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://mcp.opencommerce.sh/mcp',
    headers: { Authorization: `Bearer ${process.env.AGENTCARD_CLIENT_ID}:${process.env.AGENTCARD_CLIENT_SECRET}` },
  },
});

export async function toolsFor(shopperId: string, chatId: string) {
  const ids = { shopper_id: shopperId, thread_id: chatId };
  const tools = await mcp.tools();
  return Object.fromEntries(
    Object.entries(tools).map(([name, tool]) => {
      const properties = (tool.inputSchema as any)?.jsonSchema?.properties ?? {};
      const own = Object.fromEntries(Object.entries(ids).filter(([key]) => key in properties));
      return [name, { ...tool, execute: (args: object, options: any) => tool.execute!({ ...args, ...own }, options) }];
    }),
  );
}
```

Pass `toolsFor(shopperId, chatId)` to `generateText` or `streamText`, and call `await mcp.close()` when your server shuts down. Tools that take no ids, such as `get_account`, stay untouched.

## Make a first buy call

Call `get_account` first. It returns your `client_id` and `sandbox: true` when the credentials are sandbox ones:

```json theme={null}
{ "client_id": "<YOUR_CLIENT_ID>", "sandbox": true }
```

Then call `buy` with the shopper's own words in `ask`:

```json theme={null}
{
  "tool": "buy",
  "arguments": {
    "shopper_id": "user_8f3a21",
    "thread_id": "chat_5521",
    "ask": "two packs of AA batteries from Amazon",
    "confirm": false,
    "new_order": false,
    "product_id": null,
    "store_id": null
  }
}
```

The result holds `products` to show the shopper, each with a `product_id` you send back when the shopper picks one. Set `confirm` to `true` only on the shopper's yes to the cart you showed. In the sandbox the confirm stops at the store's checkout, and nothing is charged.

Each `buy` call answers within about 45 seconds. When `turn_continues` is `true`, Agentcard is still working: read `get_updates` later, and never send the same `buy` again.

## Keep going

* [Show products](https://docs.agentcard.com/opencommerce/guides/showing-products.md) and [show the cart](https://docs.agentcard.com/opencommerce/guides/showing-the-cart.md)
* [Send each link](https://docs.agentcard.com/opencommerce/guides/sending-each-link.md) and [take the next step](https://docs.agentcard.com/opencommerce/guides/taking-the-next-step.md)
* [Give your model instructions](https://docs.agentcard.com/opencommerce/guides/give-your-model-instructions.md), or load [the shopping skill](https://docs.agentcard.com/opencommerce/guides/give-your-model-instructions.md)
* [Test in the sandbox](https://docs.agentcard.com/opencommerce/guides/testing-in-the-sandbox.md) and [read a refusal](https://docs.agentcard.com/opencommerce/guides/reading-a-refusal.md)
* [`buy`](https://docs.agentcard.com/commerce-mcp/tools/buy) and every other tool, with its arguments and what it returns


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