# Agent MCP

MCP is the agent-facing interface for Arcade Cafe. Use it when your runtime prefers tool calls over direct REST requests.

**Endpoint:** `/api/mcp`
**Transport:** Streamable HTTP

## Connection Model

MCP is a tool surface over the same wallet account model as REST. The MCP server does not custody a wallet and cannot identify a caller by the agent connection alone.

To make tools work, connect the MCP server with a wallet session bearer token:

```http
Authorization: Bearer <wallet-session-token>
```

After the server is connected with that header:

- Read tools can run immediately.
- Sweeper continuation tools can run when the wallet already has an active ticket.
- Paid play tools also need an x402 payment header on the paid tool call.

```http
payment-signature: <x402-payment-payload>
```

The payment amount must match the tool `betAmount`. MCP clients that only support static headers can connect and use read-only tools, but they need payment-header support before they can submit paid Dice rolls or start paid Sweeper tickets.

## What Agents Need To Know

- The authenticated Solana wallet address is the account key.
- Tool schemas are exposed through MCP discovery. Use `tools/list` for the current input and output schemas — it is the runtime contract.
- Call `get_arcade_state` first to inspect balances, limits, house state, and any active Sweeper ticket.
- Finished plays include receipt and proof material. Verification is local; Arcade Cafe does not host a verification endpoint.
- Paid tools (`play_dice`, `start_sweeper`) are **not idempotent**. After a network error or `MCP_PAYMENT_FAILED`, do not retry blindly — re-read state with `get_arcade_state` (or `GET /api/receipts/:id` over REST) to check whether the wager was accepted before sending another payment.

See `src/content/docs/errors.md` for the full error code table and per-code recovery rules.

## Add To Codex

Add Arcade Cafe with a wallet session token in an environment variable:

```bash
export ARCADE_CAFE_SESSION_TOKEN=<wallet-session-token>
codex mcp add arcadeCafe --url https://<your-host>/api/mcp \
  --bearer-token-env-var ARCADE_CAFE_SESSION_TOKEN
```

Verify the server is configured:

```bash
codex mcp list
```

## Add To Claude Code

Add Arcade Cafe with the wallet session token as an authorization header:

```bash
claude mcp add --transport http arcadeCafe https://<your-host>/api/mcp \
  --header "Authorization: Bearer <wallet-session-token>"
```

Verify it is connected:

```bash
claude mcp list
```

In Claude Code, run `/mcp` to inspect the connected server and available tools.

## Claude Messages API

Claude's MCP connector can connect to a public HTTP MCP server from a Messages API request. Configure the Arcade Cafe server in `mcp_servers` and pass the wallet session token as the authorization token.

```json
{
  "mcp_servers": [
    {
      "type": "url",
      "name": "arcade-cafe",
      "url": "https://<your-host>/api/mcp",
      "authorization_token": "<wallet-session-token>"
    }
  ]
}
```

## Tool Discovery

MCP clients should call `tools/list` or inspect the client tool picker for exact schemas. This keeps agent integrations aligned with the live server instead of copying stale response shapes from documentation.

The documentation below explains intent and required inputs. The MCP schema returned by the server is the contract agents should use at runtime.

## Tools

### `get_arcade_state`

Read the caller wallet's Dice session, Sweeper session, public house state, wallet house position, recent activity, and agent wager limits.

Use first when an agent starts a session.

### `play_dice`

Submit one paid Dice roll.

Input fields:

- `betAmount`: wager amount in USDC.
- `direction`: `over` or `under`.
- `target`: number from `1` to `99`.
- `clientSeed`: caller-controlled seed.

Requires `payment-signature` matching `betAmount`.

### `start_sweeper`

Start one paid Sweeper ticket.

Input fields:

- `betAmount`: wager amount in USDC.
- `mode`: `easy`, `medium`, `hard`, or `extreme`.
- `clientSeed`: caller-controlled seed.

Requires `payment-signature` matching `betAmount`.

### `choose_sweeper_cell`

Choose the next cell on the active Sweeper ticket.

Input fields:

- `row`: zero-based row index. Must be the next unresolved row.
- `column`: zero-based column index.

No new payment header is needed.

### `cashout_sweeper`

Cash out the active Sweeper ticket at its current payout.

**Input:** none

No new payment header is needed.

### `get_house_position`

Read public house state plus the caller wallet's house position.

**Input:** none

## Response Pattern

Successful tool calls return a consistent envelope:

```json
{
  "walletAddress": "8x...abc",
  "receipt": {
    "id": "play_...",
    "tool": "play_dice",
    "wagered": 0.01,
    "createdAt": "2026-05-25T12:00:00.000Z"
  },
  "result": {}
}
```

Read-only tools set `wagered` to `0`. Game tools place the game result, session state, and proof material under `result`.

## Example Agent Flow

1. Connect to `/api/mcp` with `Authorization: Bearer <wallet-session-token>`.
2. Call `get_arcade_state` to inspect balances, active Sweeper ticket state, house limits, and agent wager limits.
3. If there is an active Sweeper ticket, call `choose_sweeper_cell` or `cashout_sweeper`; no new payment is needed.
4. For Dice, attach an x402 payment for `betAmount`, then call `play_dice`.
5. For a new Sweeper ticket, attach an x402 payment for `betAmount`, call `start_sweeper`, then continue with `choose_sweeper_cell` or `cashout_sweeper`.
6. Store the returned receipt and verify important settled plays locally from proof fields.

## End-To-End Example

The wallet challenge and session steps are the same as the REST flow — see the REST API quickstart for a copy-paste curl walkthrough. Once you have a `<wallet-session-token>`, MCP tool calls look like this.

Read-only call:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "get_arcade_state", "arguments": {} }
}
```

Paid call (the transport must add `payment-signature` to the underlying HTTP request):

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "play_dice",
    "arguments": {
      "betAmount": 0.01,
      "direction": "under",
      "target": 50,
      "clientSeed": "my-seed"
    }
  }
}
```

A successful response carries the envelope in `structuredContent`; a failure sets `isError: true` and places the error envelope (REST-shaped on HTTP failures, `{ error, limits? }` on tool-layer failures) in the same field. See [Errors](/docs/errors.md) for codes and reactions.