Claude Code MCP 3 steps

Quickstart: Add Headless Oracle to Claude Code

One .mcp.json file. No npm install. No API key required to start. Your Claude Code session gets pre-trade market verification in under a minute.

1 Copy `.mcp.json` to your project root

Choose Anonymous (no key required; 10 get_market_status calls per IP per UTC day) or Authenticated (your API key's plan limit; send the key itself):

Anonymous — no API key required

{
  "mcpServers": {
    "headless-oracle": {
      "type": "http",
      "url": "https://headlessoracle.com/mcp"
    }
  }
}

Authenticated — with your API key

{
  "mcpServers": {
    "headless-oracle": {
      "type": "http",
      "url": "https://headlessoracle.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

Auth: send your API key as Authorization: Bearer <key> (or X-Oracle-Key: <key>); calls then count against that key's plan, as on REST. An OAuth access token from POST https://headlessoracle.com/oauth/token (form-encoded grant_type=client_credentials&client_id=<key>, valid one hour) is also accepted. A Headless Oracle key or token that is not accepted (unknown, expired, out of quota) gets a JSON-RPC error, never anonymous service; other Authorization values are ignored.

Limits: Anonymous MCP allows 10 get_market_status calls per IP per UTC day. With a key, calls count against its plan: Free 500/day, Builder 50,000/day, Pro 200,000/day; only Protocol is unlimited. A free key needs no signup: POST /v5/keys/instant. A sandbox key (sb_, 200 calls over 7 days, one per IP) comes only from POST /v5/sandbox with {"email":"you@example.com"}; the key is in the response. Paid plans: headlessoracle.com/pricing.

2 Save the file as `.mcp.json` in your project root

Place it alongside your package.json or pyproject.toml. Claude Code reads this file on startup and loads the Headless Oracle tools automatically.

project-root/
├── .mcp.json          ← paste here
├── src/
└── package.json

3 Open Claude Code in that directory — tools are live

Start a new Claude Code session from your project directory. The Headless Oracle tools are available immediately. Try:

"Is NYSE open right now?"
"Check if XLON is trading before I run this script"
"What time does Tokyo open next?"
"Verify the market is open before executing this trade"

Available Tools

get_market_status: Ed25519-signed receipt (OPEN/CLOSED/HALTED/UNKNOWN) for any of 28 exchanges. Pre-trade verification gate. UNKNOWN and HALTED must be treated as CLOSED.
get_market_schedule: Next open/close times in UTC, holiday calendar, trading hours, and lunch break windows (Tokyo, HK, Shanghai).
list_exchanges: All 28 supported exchanges: NYSE, NASDAQ, London, Tokyo, Hong Kong, CME, Coinbase, Binance + 20 more.
get_payment_options: How to authenticate or pay before a request that needs a key or payment: sandbox, x402 per request, credits, subscriptions and the Chirindo Witness plans. No authentication required.

There is no MCP tool for verifying a receipt. Verify it with POST /v5/verify, or offline against the public keys at /v5/keys.

Need more than 10 calls a day?

Anonymous MCP stops at 10 get_market_status calls per IP per UTC day. A free key (500 calls/day) or a paid plan raises that limit; send it as in step 1. Only the Protocol plan is unlimited.

Get API Key → Full Docs