> ## 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 server

> Plug the Agentcard MCP server into your agent so it can act with the user's connection token.

Give your agent the card tools. Once a user has
[connected](/companies/api/user-authentication), your backend holds their
connection token — point any spec-compliant MCP client at the Agentcard MCP
server with that token and the tools load automatically. There is no service to
build here: it's a few lines of wiring in the agent you already run.

## Instructions for your agent

Paste this into your coding agent to integrate the MCP server.

```text Instructions for your agent theme={null}
You are wiring the Agentcard MCP server into this app's agent so it can act on
behalf of a connected user. We already store each user's connection
access_token + refresh_token from the connect flow.

ENDPOINT
POST https://mcp.agentcard.sh/mcp
  Authorization: Bearer <the user's connection access_token>
  Accept: application/json, text/event-stream
Standard MCP over Streamable HTTP: initialize -> notifications/initialized ->
tools/list -> tools/call, echoing the Mcp-Session-Id header. Use a
spec-compliant MCP client (e.g. @modelcontextprotocol/sdk with
StreamableHTTPClientTransport) — do not hand-roll the protocol.
The connection token IS the auth: do NOT configure OAuth on the MCP client and
never open the MCP server's hosted sign-in page in a browser. If a user ever
sees a "Connect your account" page at mcp.agentcard.sh, the client was wired
for OAuth discovery instead of the bearer token.

1. ONE CLIENT PER USER
Create the MCP client with that user's connection token. Never share a client
across users, and never expose the token outside your backend.

2. REGISTER TOOLS DYNAMICALLY
Register every tool tools/list returns instead of hardcoding names. Tools
Agentcard ships later then appear in the agent with zero code change.

3. HANDLE APPROVAL GATES
Sensitive tools (create_card, get_card_details) can return status
"approval_required" with an approval_id — nothing has happened yet. Resolve it
with approve_request. Auto-approve when the user just asked for the action;
confirm with them before revealing card credentials. NEVER write card numbers
or CVVs to logs, error reports, or analytics.

4. HANDLE EXPIRY
Connection tokens live 1 hour. On 401, refresh (with your PLATFORM access
token, not the connection token):
POST https://api.agentcard.sh/api/v2/connect/refresh
  Authorization: Bearer <platform access_token>
  { "refresh_token": "<stored>" }
-> new pair; replace BOTH stored tokens and reconnect the MCP client.

5. RELAY, DON'T FAIL
If a tool reports KYC or wallet funding is needed, relay the message to the
user and retry once they've completed it. A fresh connection listing zero
cards is expected — a token only sees the cards your app created for that
user.
```

## How it works

1. Your backend takes the connection token it stored when the user
   [authenticated](/companies/api/user-authentication).
2. Your agent's MCP client connects to `https://mcp.agentcard.sh/mcp` with that
   token as the bearer.
3. The tools load via `tools/list`, and every call the agent makes runs as that
   user — scoped to the cards your app created for them.

## The flow

<Steps>
  <Step title="Get the user's connection token">
    The `access_token` returned when the user verified their one-time code.
    Keep it fresh with the refresh token — see
    [user authentication](/companies/api/user-authentication).
  </Step>

  <Step title="Connect an MCP client">
    One client per user, pointed at `https://mcp.agentcard.sh/mcp` with
    `Authorization: Bearer <connection token>`. Any spec-compliant MCP client
    over Streamable HTTP works.
  </Step>

  <Step title="Register the tools dynamically">
    Expose everything `tools/list` returns rather than a hardcoded list — new
    tools ship into your agent automatically. See the
    [MCP overview](/companies/mcp/overview).
  </Step>

  <Step title="Handle approvals and expiry">
    Resolve `approval_required` responses with
    [approve\_request](/companies/mcp/tools/approve_request), and reconnect
    with a refreshed token when calls start returning `401`.
  </Step>
</Steps>

<Note>
  Whether the agent acts on **test** or **live** cards is set by the OAuth
  client the user connected through — a sandbox client means test cards, a
  production client means live ones. See [Production](/companies/production).
</Note>

## What your agent can do

Every tool has its own page with parameters, returns, and an example call.
The main areas:

<CardGroup cols={2}>
  <Card title="Cards" icon="credit-card" href="/companies/mcp/tools/create_card">
    Create, pause, resume, and close cards, update limits, and list
    transactions.
  </Card>

  <Card title="Balance" icon="wallet" href="/companies/mcp/tools/get_balance">
    Check the cash balance, add funds, and withdraw.
  </Card>

  <Card title="Shopping" icon="cart-shopping" href="/companies/mcp/tools/buy">
    The conversational `buy` tool covers the whole flow — search stores and
    products, build a cart, and check out.
  </Card>

  <Card title="Approvals & KYC" icon="shield-check" href="/companies/mcp/tools/approve_request">
    Approve sensitive actions and run identity verification when a tool asks
    for it.
  </Card>

  <Card title="Payment methods" icon="money-check" href="/companies/mcp/tools/setup_payment_method">
    Set up, list, and manage the user's payment methods.
  </Card>

  <Card title="Rewards" icon="gift" href="/companies/mcp/tools/get_rewards">
    Check and redeem rewards.
  </Card>

  <Card title="Account" icon="user" href="/companies/mcp/tools/whoami">
    Identify the connected user, manage their plan, settings, and connections.
  </Card>

  <Card title="Support" icon="headset" href="/companies/mcp/tools/start_support_chat">
    Open a support chat, send messages, and read replies.
  </Card>
</CardGroup>