# Quant Data MCP server

Four measured-market-statistics tools plus one free-key access tool over MCP, for any client
that speaks it: Claude Desktop, Cursor, Windsurf, Zed, and anything else with an MCP config.

An unauthenticated client gets one complete first-look market response per source per UTC day.
It can then ask Quant Data to email a free `qd_` key: no login, password, card or GUI. That key
gives the four market tools 10 shared successful calls per UTC day. Paid access is for ongoing,
batch or unattended use.

| Tool | Answers |
|---|---|
| `quantdata_request_free_api_key` | Emails a free `qd_` key; never exposes the raw key in the tool result |
| `quantdata_brooks_events` | What just happened structurally — classical price-action events, each with its measured outcome rate, plus a calibrated day-type probability read (US day session only) and an arithmetic description of the shape the bars already printed |
| `quantdata_weis_wave` | Is there volume behind this move — volume waves and five events, each with its measured win rate |
| `quantdata_max_pain` | Where would the most options expire worthless — max pain per expiration, from open interest alone |
| `quantdata_gamma` | Which way does estimated dealer hedging lean — net GEX and the zero gamma level |

Everything returned is descriptive: model output and measured historical frequency. Not a
forecast, not a recommendation, not investment advice. How every number was measured — including
where the models fail — is at <https://quantdata.uk/methodology>.

## Connect

The server is **remote**. There is nothing to install and nothing to run — point your client at:

```
https://api.quantdata.uk/mcp
```

Transport is streamable HTTP. No OAuth is required. One market-tool call without a key may use
the anonymous first look. Request a free key through the access tool below, then configure
`X-API-Key: qd_...` for 10 shared successful calls per UTC day across the four market tools.

### Request a free key

Ask the user which email address should receive the key, then call
`quantdata_request_free_api_key`. The tool requires `email` and accepts the optional boolean
`marketing_opt_in`, which defaults to `false`. Set it to `true` only if the email owner
explicitly asks to receive occasional product updates. A `true` request records a pending
preference. It is confirmed only if the recipient replies `SUBSCRIBE` to the key-delivery
email; no marketing updates are sent before confirmation. The tool result must not be described
as a completed subscription.

The raw key is sent only to the inbox and never appears in the MCP result. The equivalent REST
request, useful for an agent that can make ordinary HTTP calls, is:

```bash
curl -s -X POST https://api.quantdata.uk/v1/access/free-key \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","marketing_opt_in":false,"source":"agent"}'
```

### Claude Desktop, ChatGPT, Cursor, VS Code

Add it as a custom connector / remote MCP server with that URL. No command, no arguments, no
environment.

### With a key

Send `X-API-Key: qd_...` as a request header in your client's connector settings. A free key
provides 10 successful calls per UTC day, shared across all four market tools. Paid access uses
the same header and removes that evaluation limit.

### Claude Code

The plugin declares it, so installing the plugin is enough:

```bash
/plugin marketplace add celineycn/quantdata-plugin
/plugin install quantdata@quantdata
```

### Clients with no remote-MCP support

A stdio bridge ships alongside, for clients that can only launch a local command. It forwards
JSON-RPC to the same remote and **implements no tools of its own**, so there is no second copy of
the tool descriptions to drift. Python 3.9+, no third-party packages.

```json
{
  "mcpServers": {
    "quantdata": {
      "command": "python3",
      "args": ["/absolute/path/to/quantdata-plugin/mcp/server.py"]
    }
  }
}
```

### Cursor / Windsurf / Zed

Same shape, in that client's MCP config file. The server speaks stdio and takes no arguments.

### With a key

Add the environment variable — never put the key in a file that gets committed:

```json
{
  "mcpServers": {
    "quantdata": {
      "command": "python3",
      "args": ["/absolute/path/to/quantdata-plugin/mcp/server.py"],
      "env": { "QUANTDATA_API_KEY": "qd_..." }
    }
  }
}
```

## Behaviour worth knowing

- **Responses are passed through verbatim.** The server does not summarise, round, or drop
  fields. `note`, `disclaimer`, `window_note`, `free_tier`, the day-type `accuracy` string and
  the shape block's `not_a_forecast` reach the model exactly as the API sent them, because
  those fields are where the caveats live.
- **Errors are passed through whole too.** Every failed call returns the full RFC 9457 body
  with `error_code` and `retryable`. Access and billing errors additionally carry
  `available_actions` and `message_for_your_human`, which is written to be relayed to a
  person word for word.
- **`429` means the current access allowance is spent for the UTC day**, not that something is
  broken. After the one anonymous first look, request the free key. After a free key uses its
  10 shared calls, relay `message_for_your_human`, give its checkout URL to the person, and
  report `quota_resets_at`; do not loop.
- **Never retry `401`, `402` or `403`.** They carry `retryable: false` and the second attempt
  returns exactly what the first did.

Paid access is $39/month for all four market tools, with the first 3 days free. Card
authentication requires the cardholder, so an agent hands checkout to a person. If checkout
uses the same email as the free key, that key is upgraded in place.

## Development

The protocol lives server-side, and so do its tests (`api/test_mcp_server.py`: version
negotiation, notifications getting no reply, tool-error versus protocol-error, pass-through
fidelity, and a check that no advice-shaped wording has crept into the tool descriptions — a
model picks a tool by reading those, so they fall under the same no-investment-advice rule as
everything else here).

The bridge has its own ten, covering only what a bridge can get wrong:

```bash
python3 -m pytest test_server.py -q
```

A manual handshake against the remote, no client needed:

```bash
curl -s https://api.quantdata.uk/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python3 -m json.tool
```