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

# MCP

> One Agentcard MCP server, three toolsets: your organization's, your users', and your own.

There is one Agentcard MCP server, at `https://mcp.agentcard.sh/mcp`. What it exposes depends on the credential you connect with: your organization, one of your users, or your own personal account. Connecting with the wrong credential gives you the wrong toolset, not an error.

## Install

```bash theme={null}
npx -y agent-cards setup-mcp
```

One command for Claude Code. A browser sign-in appears the first time a tool runs. For any other MCP client, add the URL and an `Authorization` header to its config.

## Connect as your organization

Run your whole integration from your coding agent, with the same credentials you use for the API:

```bash theme={null}
claude mcp add agentcard --transport http https://mcp.agentcard.sh/mcp \
  --header "Authorization: Bearer YOUR_CLIENT_SECRET"
```

Sandbox or production follows the credential, like everywhere else.

### Organization tools

| Area            | Tools                                                                                                                |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| Users           | `create_cardholder` · `list_cardholders` · `get_cardholder` · `create_onboarding_session` · `get_onboarding_session` |
| Identity        | `start_cardholder_kyc` · `get_cardholder_kyc_status`                                                                 |
| Cards           | `create_card` · `list_cards` · `get_card` · `get_card_details` · `close_card`                                        |
| Payment methods | `setup_cardholder_payment_method` · `get_cardholder_payment_method_status`                                           |
| Company balance | `get_company_wallet` · `list_transfers` · `confirm_collection` · `recover_funds` · `list_recoveries`                 |
| Testing         | `test_charge` simulates a full sandbox charge: authorization, settlement, and every webhook                          |
| Support         | `ask_agentcard_engineer` · `get_engineer_reply` · `report_agentcard_issue`                                           |
| Session         | `whoami` · `mint_buy_token`                                                                                          |

When something breaks during your integration, connect this server and ask your agent to debug it. It reads the same state we see.

## Connect as one of your users

Your users' agents connect to the same URL with the user's connection `access_token`, the token your server stored in [Authenticating a user](/issuing/authenticating-a-user). One client per user, never shared: the bearer decides whose cards and purchases the agent can see.

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

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.agentcard.sh/mcp"),
  { requestInit: { headers: { Authorization: `Bearer ${user.agentcardAccessToken}` } } },
);
const client = new Client({ name: "your-app", version: "1.0.0" });
await client.connect(transport);
const { tools } = await client.listTools();
```

Register whatever `listTools()` returns rather than a hardcoded list, so tools Agentcard ships later appear without a deploy on your side.

### User tools

| Area         | Tools                                                                                                                                                                                                                                                                     |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Shopping     | `buy` is the whole purchase loop. `buy_list_merchants`, `buy_connect` and `buy_connect_status` handle merchants that need the user to link an account first. `buy_track_order`, `buy_order_history`, `buy_return_order` and `buy_return_status` cover what happens after. |
| Cards        | `create_card` · `list_cards` · `get_card_details` · `get_card_balance` · `pause_card` · `resume_card` · `update_card_limit` · `close_card`                                                                                                                                |
| Vault        | `get_wallet_link` with `purpose: "add_card"` mints the link that puts the user's own card in the Vault. `list_added_cards` · `remove_added_card`                                                                                                                          |
| Balance      | `get_balance` · `add_funds` · `start_phone_verification` · `verify_phone`                                                                                                                                                                                                 |
| Identity     | `start_kyc` · `submit_kyc_document` · `check_kyc_document` · `submit_kyc_fields` · `get_kyc_status`                                                                                                                                                                       |
| Rewards      | `get_rewards` · `redeem_rewards` · `redeem_code` · `list_codes`                                                                                                                                                                                                           |
| Transactions | `list_transactions` · `list_transactions_by_payment_method` · `list_all_transactions`                                                                                                                                                                                     |
| Session      | `whoami` · `get_instructions` · `get_settings` · `update_settings` · `get_plan`                                                                                                                                                                                           |

Approvals are deliberately absent. An approval is the user's own consent, so `list_pending_approvals` and `approve_request` answer `personal_surface_only` to a connected session. The user resolves it from the emailed link or their own Agentcard session, and your agent retries with the `approval_id`.

## Rules for your agent

```text theme={null}
- The credential decides the server. Your org credential gets the organization tools; a user's connection token gets that user's tools, including buy.
- Keep the client secret in your own MCP config, on your machine or server. Never in a browser or a shared config.
- One client per user, never shared.
- Call get_instructions once before the first buy; it carries the current usage guide.
- On 401, refresh the connection with your org token (POST /api/v2/connect/refresh), replace both stored tokens, and reconnect the client.
- Never write card numbers or CVVs to logs, error reports, or analytics.
```