> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magicmarkets.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Let Claude and other agents read and trade MagicMarkets markets, through the local server in the CLI or the hosted server at magicmarkets.com/mcp.

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](#hosted-mcp) that needs no install and has no read-only default.

<Note>
  The MCP server is in developer mode, and its tool set may still change. Install the [CLI](/developers/tools/cli) first. If a client cannot find `magicmarkets`, put the absolute path from `which magicmarkets` in `command`.
</Note>

## Add it to Claude Code

```bash theme={"dark"}
claude mcp add magicmarkets -e MAGICMARKETS_API_KEY=your-key -- magicmarkets mcp
```

## Add it to any MCP client

```json theme={"dark"}
{
  "mcpServers": {
    "magicmarkets": {
      "command": "magicmarkets",
      "args": ["mcp"],
      "env": { "MAGICMARKETS_API_KEY": "your-key" }
    }
  }
}
```

## Serve over localhost HTTP

One long-running server can serve several clients:

```bash theme={"dark"}
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:

```json theme={"dark"}
{
  "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 |

```json theme={"dark"}
"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:

```bash theme={"dark"}
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](/developers/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 |

<Warning>
  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.
</Warning>

### Add it to Claude Code

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

```bash theme={"dark"}
claude mcp add --transport http magicmarkets https://magicmarkets.com/mcp
```

With an API key:

```bash theme={"dark"}
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](/developers/tools/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](/developers/tools/machine-readable-docs).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.