# AgentCard MCP Server

Prepaid virtual Visa cards for AI agents. Create cards, check balances, retrieve payment credentials, and make [x402](https://www.x402.org/) payments — all through the [Model Context Protocol](https://modelcontextprotocol.io/).

## What It Does

AgentCard lets AI agents spend money online with hard budget limits. Each card is a prepaid Visa with a fixed USD balance that works anywhere Visa is accepted (card-not-present). The MCP server exposes 10 tools:

| Tool | Description |
|------|-------------|
| `list_cards` | List all virtual cards with balances, expiry, and status |
| `create_card` | Create a new prepaid Visa (returns Stripe checkout URL for funding) |
| `get_card_details` | Get decrypted PAN, CVV, expiry (requires human approval via email) |
| `check_balance` | Fast balance check without exposing credentials |
| `close_card` | Permanently close a card (irreversible) |
| `get_funding_status` | Poll card creation status after Stripe payment |
| `x402_fetch` | HTTP fetch with automatic payment on 402 responses |
| `start_support_chat` | Start a support conversation |
| `send_support_message` | Send a message in a support thread |
| `read_support_chat` | Read support conversation history |

## Install

### Quick Start (Recommended)

The fastest way to get started is with the AgentCard CLI, which handles authentication and MCP setup automatically:

```bash
npx agent-cards signup    # create an account
npx agent-cards setup-mcp # configure MCP in Claude Code
```

This registers the hosted MCP server (`https://mcp.agentcard.sh/mcp`) with your credentials.

### Manual Setup (Claude Code / Claude Desktop)

If you prefer manual configuration, add to your MCP config (`claude_desktop_config.json` or `.mcp.json`):

```json
{
  "mcpServers": {
    "agent-cards": {
      "type": "http",
      "url": "https://mcp.agentcard.sh/mcp",
      "headers": {
        "Authorization": "Bearer <your-jwt-token>"
      }
    }
  }
}
```

Get your JWT token by running `npx agent-cards login` or from the [dashboard](https://agentcard.sh/dashboard).

### Docker (Self-Hosted)

```bash
docker build -t agent-cards-mcp .
docker run -p 8080:8080 -e AGENT_CARDS_JWT=<your-jwt> agent-cards-mcp
```

> **Roadmap**: Standalone `npx agent-cards-mcp` support (without the CLI signup step) is planned for a future release.

## Setup

1. Install the CLI: `npx agent-cards signup`
2. Configure MCP: `npx agent-cards setup-mcp`
3. Restart Claude Code — the AgentCard tools will be available

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `AGENT_CARDS_JWT` | Yes | Your AgentCard JWT token |
| `AGENT_CARDS_API_URL` | No | API URL (default: `https://api.agentcard.sh`) |
| `CARD_PAYMENT_SECRET` | No | Secret for x402 card payments (server-side only) |

## Security Model

- **Human-in-the-loop**: `create_card` and `get_card_details` require email approval from the account owner before proceeding
- **Encryption at rest**: Card credentials (PAN, CVV) are encrypted with AES-256-GCM
- **Audit trail**: Every MCP tool call includes `X-Caller-Type` and `X-Correlation-ID` headers
- **Budget limits**: Each card has a hard spending cap set at creation — the agent cannot exceed it
- **Stateless**: Each HTTP request creates a fresh server instance with no shared state

## Development

```bash
git clone https://github.com/radiahq/mcp.git
cd mcp
npm install
npm run dev        # stdio mode
npm run dev:http   # HTTP mode (port 3002)
```

## Links

- [Website](https://agentcard.sh)
- [Dashboard](https://agentcard.sh/dashboard)
- [Documentation](https://agentcard.sh/blog/how-agentcard-works)
- [CLI on npm](https://www.npmjs.com/package/agent-cards)

## License

MIT