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

# MCP Server

> Connect AI assistants and agents to Belief index and Belief Volatility data over the Model Context Protocol – keyed setup, tools reference, rate limits, and licensing scope.

**Endpoint:** `https://beliefsystems.xyz/api/mcp` (MCP Streamable HTTP)
**Authentication:** `Authorization: Bearer belief_live_…` – [get a free key](https://beliefsystems.xyz/data)

<Warning>
  As of August 29, 2026, the MCP server requires a free API key. Add an `Authorization` header to your client config – setup below. Tool names, arguments, and responses are unchanged.
</Warning>

The Belief Systems MCP server gives AI assistants and software agents structured access to the public data surface: the index catalog and per-index detail, chart-grade level history, the Belief Volatility series with the disclosures that must travel with them, and the point-in-time snapshot downloads.

<Info>
  The server mirrors the public data surface exactly. What sits outside it, and where that data
  lives instead, is in [Data boundaries](/data-access/data-api-boundaries).
</Info>

## Setup

Create a key at [beliefsystems.xyz/data](https://beliefsystems.xyz/data). The Claude Code command takes the key from `BELIEF_API_KEY` in your shell and writes it into the client's config, so rotating a key means re-running the command. The JSON config takes the secret directly, so paste it where `belief_live_…your key…` appears. The Codex command stores the variable name rather than the value and reads it at call time, so a rotated key is picked up by re-exporting it.

<CodeGroup>
  ```bash Claude Code theme={null}
  claude mcp add --transport http belief-systems \
    https://beliefsystems.xyz/api/mcp \
    --header "Authorization: Bearer $BELIEF_API_KEY"
  ```

  ```json Claude Desktop / Cursor theme={null}
  {
    "mcpServers": {
      "belief-systems": {
        "type": "http",
        "url": "https://beliefsystems.xyz/api/mcp",
        "headers": {
          "Authorization": "Bearer belief_live_…your key…"
        }
      }
    }
  }
  ```

  ```bash OpenAI Codex theme={null}
  codex mcp add belief-systems \
    --url https://beliefsystems.xyz/api/mcp \
    --bearer-token-env-var BELIEF_API_KEY
  ```
</CodeGroup>

The portal's MCP section carries the same snippets, and the dialog that shows a new key gives you one with the key already in it.

If a tool call that worked yesterday now returns an error asking for a key, that is this change and not your configuration. Add the header. If you have a key but the error says it is not valid, it has been revoked or rotated – mint a new one in the [portal](https://beliefsystems.xyz/data/portal).

## Tools

| Tool                     | Arguments           | Returns                                                                                                                                                                                       |
| ------------------------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_indices`           | –                   | The catalog of published indices: ticker, name, current level, inception date, publication status.                                                                                            |
| `get_index`              | `ticker`            | One index: level, inception, data quality, and links to the index page, a citable chart PNG, and downloads.                                                                                   |
| `get_index_history`      | `ticker`, `horizon` | Chart-grade level history: up to 300 points of `{ t, indexLevel, stale }`, plus % change over the window.                                                                                     |
| `list_volatility_series` | –                   | The Belief Volatility catalog: ticker, name, headline value in probability points, the tenor the bare ticker denotes, publication state.                                                      |
| `get_volatility_index`   | `ticker`            | One Belief Volatility series with every disclosure that travels with it: release share per tenor, measure and tier labels, sensitivity band, frozen-prices counterfactual, per-leg breakdown. |
| `get_volatility_history` | `ticker`, `horizon` | Chart-grade Belief Volatility history with release shares and measure labels.                                                                                                                 |
| `get_data_downloads`     | –                   | The current point-in-time snapshot: manifest, per-series CSV URLs, data dictionary, citation file.                                                                                            |
| `get_citation_guidance`  | –                   | Attribution, licensing, and framing rules for quoting the data.                                                                                                                               |

Argument details:

* `ticker` – index or series ticker, e.g. `CONFLICT`, `MIDR26`, `MIDVOL`. Case-insensitive. Use `list_indices` or `list_volatility_series` for the catalogs.
* `horizon` – one of `24h`, `7d`, `30d`, `all`. Defaults to `30d`. The windows match the citable chart PNG endpoint, so a quoted number and its chart always agree. `all` means since inception, clamped to the trailing 90-day free window; full history is in the snapshot downloads.

Every response carries the attribution line `Source: Belief Systems (beliefsystems.xyz)`.

<Note>
  The MCP server now runs on the `/v1` [Data API](/data-access/data-api). Tool names and schemas are unchanged; the one change existing clients need is the `Authorization` header.
</Note>

## Rate limits and fair use

* **60 requests per minute and 2,000 per day, per key.** MCP calls and direct API calls draw on the same two windows and appear in the same usage record in the portal. Exceeding either returns an error quoting your limits and `Retry-After`. Full detail: [Limits and errors](/data-access/data-api-limits).
* **A separate per-address bucket sits in front of the endpoint** as an abuse shield, sized for interactive agent use rather than bulk collection. A client behaving normally never meets it.
* History responses are chart-grade: capped at 300 downsampled points per call.

## Scope and licensing

The endpoint is offered to registered account holders under a limited, revocable grant for **evaluation, research, and internal business analytics** – including use by AI assistants and agents acting on your behalf – with attribution. You may quote, cite, and display individual values in research, commentary, and editorial work, including externally published work.

A separate written license covers:

* redistribution
* incorporation into a product, feed, benchmark, fund, or index-linked instrument
* use in a production system relied on by you or a third party
* extraction beyond the limits published for your keys

The exact language is in [Terms of Service, Section 7](https://beliefsystems.xyz/terms). Keys are personal to the individual who registered the account; each person needing access registers separately.

For live feeds, full-fidelity history, constituent detail, redistribution, or product use, see [Index Services](https://beliefsystems.xyz/license) or [request access](https://beliefsystems.xyz/access?source=docs-mcp).

## Related surfaces

* [Data API](/data-access/data-api) – the same data as a REST surface, on the same key
* [Point-in-time snapshots](/data-access/downloads) – per-series CSVs for research and editorial use
* [llms.txt](https://beliefsystems.xyz/llms.txt) – machine-readable site guide
* [Index Calculation Methodology](/indices/nav-methodology) – how index levels are computed