MCP server

The magicmarkets binary serves the Model Context Protocol over stdio, or over HTTP on localhost. Point an agent at it and the agent can list events, read offers, check your balance and position, and, only if you allow it, quote and place orders. The local server is read-only by default. Trading tools appear only when you set MAGICMARKETS_ALLOW_TRADING=1. MagicMarkets also runs a hosted MCP server that needs no install and has no read-only default.

The MCP server is in developer mode, and its tool set may still change. Install the CLI first. If a client cannot find magicmarkets, put the absolute path from which magicmarkets in command.

Add it to Claude Code

claude mcp add magicmarkets -e MAGICMARKETS_API_KEY=your-key -- magicmarkets mcp

Add it to any MCP client

{
  "mcpServers": {
    "magicmarkets": {
      "command": "magicmarkets",
      "args": ["mcp"],
      "env": { "MAGICMARKETS_API_KEY": "your-key" }
    }
  }
}

Serve over localhost HTTP

One long-running server can serve several clients:

magicmarkets mcp --http --addr 127.0.0.1:8383

In this mode the server does not read MAGICMARKETS_API_KEY. Each request sends the caller’s key in an X-Api-Key header:

{
  "mcpServers": {
    "magicmarkets": {
      "url": "http://127.0.0.1:8383/mcp",
      "headers": { "X-Api-Key": "your-key" }
    }
  }
}

The address is loopback only by default, and the server has no TLS of its own.

Tools

Read-only by default, 11 tools:

Tool	What it does
`get_balance`	Balance and open stake
`get_exchange_rates`	Exchange rates
`get_position`	Current positions
`list_events`	Every event with live prices, from the stream snapshot
`list_event_offers`	The book for one event, both sides
`list_orders`	Your orders
`get_order`	One order
`list_betslips`	Your betslips
`get_betslip`	One betslip
`validate_bet_type`	Check a bet type string
`snap_price`	Snap a price to the tick schedule

With MAGICMARKETS_ALLOW_TRADING=1, eight more:

Tool	What it does
`create_betslip`	Quote a selection
`place_order`	Place an order against a betslip
`close_order`	Close one order
`close_all_orders`	Close every open order, or only those on one sport or event
`create_heartbeat`, `refresh_heartbeat`, `cancel_heartbeat`, `list_heartbeats`	Heartbeat lifecycle

"env": { "MAGICMARKETS_API_KEY": "your-key", "MAGICMARKETS_ALLOW_TRADING": "1" }

A client reads the tool list once at startup. After you change MAGICMARKETS_ALLOW_TRADING, replace the registration and restart the client. Run magicmarkets mcp --print-tools to list what is registered with your current settings.

Why read-only by default

The trading tools are registered only when MAGICMARKETS_ALLOW_TRADING is set as the server starts, so a prompt cannot switch them on. The tools that spend money or close orders carry MCP destructive hints, so a client that honours hints asks before it calls them.

Pairing with a heartbeat

If you let an agent trade, run a heartbeat in a separate terminal:

magicmarkets heartbeat run --timeout 60

If that process or the machine stops, the heartbeat expires and every open order on the account closes. Ctrl-C cancels the heartbeat and leaves orders open. With trading enabled, the agent can also manage its own heartbeat with the heartbeat tools. See Safety.

Hosted MCP

MagicMarkets runs a hosted MCP server. You do not install anything.


Endpoint	`https://magicmarkets.com/mcp`
Transport	Streamable HTTP (JSON-RPC over POST), protocol version `2025-06-18`
Authentication	An `X-Api-Key: <key>` header, or OAuth 2.1 sign-in with your MagicMarkets account

The hosted server has no read-only default. Trading tools are available to any authenticated client, and place_order spends real money. Use a client that asks before each tool call.

Add it to Claude Code

With OAuth sign-in. The client asks you to sign in to MagicMarkets on first use:

claude mcp add --transport http magicmarkets https://magicmarkets.com/mcp

With an API key:

claude mcp add --transport http magicmarkets https://magicmarkets.com/mcp \
  --header "X-Api-Key: $MAGICMARKETS_API_KEY"

If you also run the local server, give one of the two registrations a different name.

OAuth for other clients

The server uses the OAuth 2.1 authorization code flow with PKCE (S256), dynamic client registration and the scope mcp. A client discovers the details at https://magicmarkets.com/.well-known/oauth-protected-resource and https://magicmarkets.com/.well-known/oauth-authorization-server.

Tools

The hosted server exposes the same 19 tools as the local server: the 11 tools in the first table and the 8 trading tools in the second. All 19 are available as soon as a client authenticates.

Hosted or local

	Hosted	Local
Install	None	The CLI
Runs on	magicmarkets.com	Your machine
Authentication	`X-Api-Key` header or OAuth sign-in	`MAGICMARKETS_API_KEY`, or an `X-Api-Key` header in HTTP mode
Trading tools	Always available	Only with `MAGICMARKETS_ALLOW_TRADING=1`

This server trades on your account. It is separate from the docs MCP server at magicmarkets.com/docs/mcp, which only searches and reads these docs. See Machine-readable docs.

Start here

Concepts

Streaming

Guides

Tools

API reference

Endpoints

Updates

Add it to Claude Code

Add it to any MCP client

Serve over localhost HTTP

Tools

Why read-only by default

Pairing with a heartbeat

Hosted MCP

Add it to Claude Code

OAuth for other clients

Tools

Hosted or local

​Add it to Claude Code

​Add it to any MCP client

​Serve over localhost HTTP

​Tools

​Why read-only by default

​Pairing with a heartbeat

​Hosted MCP

​Add it to Claude Code

​OAuth for other clients

​Tools

​Hosted or local

Add it to Claude Code

Add it to any MCP client

Serve over localhost HTTP

Tools

Why read-only by default

Pairing with a heartbeat

Hosted MCP

Add it to Claude Code

OAuth for other clients

Tools

Hosted or local