Claude Code MCP 3 steps

Quickstart: Add Headless Oracle to Claude Code

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

1

Copy .mcp.json to your project root

Choose Sandbox (no key required, 200 calls free) or Authenticated (unlimited, requires API key):

Sandbox — no API key required 
{
  "mcpServers": {
    "headless-oracle": {
      "type": "url",
      "url": "https://headlessoracle.com/mcp"
    }
  }
}
Authenticated — with API key 
{
  "mcpServers": {
    "headless-oracle": {
      "type": "url",
      "url": "https://headlessoracle.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}
Sandbox: Auto-provisions 200 calls over 7 days on first use. No signup required. Use headlessoracle.com/upgrade for an unlimited API key.
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.

verify_receipt

Verify the Ed25519 cryptographic signature on a receipt you received from another agent.

Need more than 200 calls?

Sandbox keys expire after 7 days and have a 200-call limit. Upgrade to an API key for unlimited access.

Get API Key → Full Docs