# Install the MCP server (/docs/mcp)



Kestrel Markets speaks the **Model Context Protocol** so an agent drives the platform
natively — the same operations as the [canonical HTTP face](/docs/concepts/four-faces),
projected as MCP tools. This page is the one **verified** install path: a single
copy-paste snippet that connects on the first try.

> **Anonymous by default (ADR-0002)**
>
> The MCP face is dual-mode. It admits an **anonymous trial** with no key and no
> signup — discover the tools, mint a trial, run a free sim, reach a certified proof
> URL. OAuth 2.1 layers on only when you need wallet or human scope.

## Connect [#connect]

* **Endpoint** — `https://mcp.kestrel.markets/mcp` (Streamable HTTP, protocol `2025-11-25`)
* **Headers** — none required. The one-line command below connects as-is.

The MCP face answers on two equivalent hostname forms: the dedicated subdomain at
`https://mcp.kestrel.markets/mcp`, and the apex at `https://kestrel.markets/mcp`.
On the `mcp.` subdomain the bare root (`https://mcp.kestrel.markets/`) aliases to the
same transport, so an already-`/mcp` path is never double-prefixed. Use either; the
snippets below use the subdomain.

No `Origin` header is required. The transport validates Origin **only when it is
present** — DNS-rebinding protection is a browser threat, and a browser always sends a
truthful, unforgeable Origin, so a *present* Origin must be allow-listed (else `403`).
A non-browser machine client that sends no Origin is admitted, so the bare `claude mcp
add http` below connects on the first try with no extra flags.

### Claude Code / Claude Desktop [#claude-code--claude-desktop]

```bash
claude mcp add --transport http kestrel-markets https://mcp.kestrel.markets/mcp
```

That registers the server as `kestrel-markets`. Verify it connected:

```bash
claude mcp list
```

### Any MCP client (`mcpServers` config) [#any-mcp-client-mcpservers-config]

For clients configured by file (Claude Desktop's `claude_desktop_config.json` and
other Streamable-HTTP-aware clients), add:

```json
{
  "mcpServers": {
    "kestrel-markets": {
      "type": "http",
      "url": "https://mcp.kestrel.markets/mcp"
    }
  }
}
```

## What you get [#what-you-get]

`initialize`, then `tools/list` returns the projected tool set. It includes the
seven public ADR-0004 operations, each a thin equal projection of the canonical
HTTP endpoint:

* `capability_discovery` — the always-available self-description of the platform
* `catalog` — browse the free derived-data catalog
* `validate` — check a control document without spending (`source` is the Kestrel text)
* `simulate` — run a metered, certified sim over a dataset (takes `source`, plus a
  `dataset.artifact_id` from the catalog)
* `grade` — the signed black-box receipt every sim certifies
* `proof` — resolve a public, re-verifiable certified proof URL
* `offers` — the 402 continuation quoted against work already underway

The list also carries the capability-gated portfolio-manager fleet surface
(`fleet_*`, `pod_*`, `agent_*`, `leaderboard_get`). Those tools are never
anonymous, and out of scope for the trial funnel.

Nothing about the funnel changes from the [Quickstart](/docs/quickstart) — MCP is
the same four requests in a different envelope. One naming note: over MCP the
Kestrel document travels as `source`, where the HTTP quickstart shows `strategy`
(the HTTP face accepts both). No raw licensed market data is ever served over any
face; only derived, certified artifacts.

## OAuth (wallet + human scope) [#oauth-wallet--human-scope]

The anonymous trial can never carry `paper`, `broker`, `live`, or `wallet` scope. To
settle an Offer and resume an Operation you authorize with a signer over OAuth 2.1.
Discovery is standard:

```bash
curl -sS https://mcp.kestrel.markets/.well-known/oauth-protected-resource
```

That Protected-Resource-Metadata document names the authorization server and the
grantable scopes. See [Activation](/docs/activation) for the settle-and-resume path.

## Registry listing [#registry-listing]

Kestrel Markets publishes a canonical Model Context Protocol `server.json` manifest
for registry listing. It declares the Streamable-HTTP remote with no required
connection header, matching this page exactly.