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:

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.
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:

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:

codex mcp list

Add To Claude Code

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

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

Verify it is connected:

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.

{
  "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:

{
  "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:

{
  "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):

{
  "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 for codes and reactions.