# Index One MCP Server

Remote [MCP](https://modelcontextprotocol.io) server for [Index One](https://indexone.io) — query financial index data, run backtests, and build and deploy systematic investment strategies from any MCP-capable client.

| | |
|---|---|
| **Endpoint** | `https://api.indexone.io/mcp` |
| **Transport** | Streamable HTTP (stateless, POST only) |
| **Auth** | OAuth 2.1, or a team API key in `x-api-key` |
| **Tools** | 22 |
| **Registry** | [`io.indexone/mcp`](https://registry.modelcontextprotocol.io/v0/servers?search=io.indexone) |
| **Docs** | https://indexone.io/docs/mcp |

> This repository is the public home for the server's manifest, tool reference and client examples. The server itself is hosted by Index One — there is nothing to install, build or run locally, and the server implementation is not open source.

## What it does

Index One builds and calculates custom financial indices. The MCP server exposes that platform as tools, so an agent can:

- **Read index data** — metadata, historical value series, holdings, weightings, universes, and risk/return statistics for your team's indices and public ones.
- **Backtest** — simulate any index definition over history, with performance summaries and value series.
- **Build and deploy** — discover the workflow operations and datasets available, preview a workflow against real data, validate it, save it as a draft, and deploy it as a live, continuously calculated index.

The server is a tool surface, not a chatbot: your client's own model does the reasoning and calls tools one at a time. Every call is scoped to your team.

## Authentication

**OAuth** — clients that implement the MCP authorization spec (the Claude web and Desktop connectors, among others) need only the endpoint URL. You'll be sent to a sign-in page and log in with your normal Index One account; no key ends up in a config file.

**API key** — everything else sends a team API key as the `x-api-key` header. This covers Claude Code, Cursor, VS Code and custom agents, which register on a random local port that OAuth providers can't pre-approve. Create and revoke keys in the Index One console under **Team → API Keys**.

Both resolve to the same team scope. Rate limit is roughly 60 calls per minute per team; over that you get `429` with `Retry-After`.

## Quick start

### Claude (web or Desktop) — connector

Settings → Connectors → Add custom connector, paste `https://api.indexone.io/mcp`, leave the advanced OAuth fields empty, and sign in with your Index One account.

### Claude Code

```bash
claude mcp add --transport http indexone https://api.indexone.io/mcp \
  --header "x-api-key: YOUR_API_KEY"
```

### Cursor — `~/.cursor/mcp.json`

```json
{
  "mcpServers": {
    "indexone": {
      "url": "https://api.indexone.io/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}
```

### VS Code — `.vscode/mcp.json`

```json
{
  "servers": {
    "indexone": {
      "type": "http",
      "url": "https://api.indexone.io/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}
```

### Claude Desktop — `claude_desktop_config.json`

Desktop reaches remote servers through the `mcp-remote` bridge:

```json
{
  "mcpServers": {
    "indexone": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://api.indexone.io/mcp",
        "--header", "x-api-key:${INDEXONE_API_KEY}"
      ],
      "env": { "INDEXONE_API_KEY": "YOUR_API_KEY" }
    }
  }
}
```

On Windows, use `"command": "cmd"` with `"args": ["/c", "npx", ...]` — Desktop resolves `npx` to a path containing a space, which breaks the launch. Write the header with no space after the colon; Desktop does not escape spaces inside arguments.

### Anything else

See [`examples/`](examples/) for a raw JSON-RPC call over curl and a Python client using the official MCP SDK.

## Tools

Full reference with descriptions: [**TOOLS.md**](TOOLS.md).

| Group | Tools |
|---|---|
| Index data | `get_index`, `get_index_values`, `get_index_holdings`, `get_index_weightings`, `get_index_universe`, `get_index_stats` |
| Backtesting | `run_backtest`, `get_backtest` |
| Discovery | `list_operations`, `get_operations`, `list_examples`, `get_example`, `list_workflows`, `get_workflow`, `list_datasets`, `inspect_dataset` |
| Preview | `run_workflow`, `inspect_run`, `get_column_values` |
| Persistence | `validate_workflow`, `save_workflow`, `deploy_index` |

Writes are deliberately narrow: an agent can save drafts and deploy an index — the latter only with `confirm=true`, after a full backtest, and never as an empty index — and there is no delete tool.

## Building an index

An index workflow is a DAG of operations: a trigger that sets the schedule, operations that select, filter and weight securities, and a `create_index_holdings` step that turns the result into holdings. Agents discover that shape rather than assuming it. The server ships instructions telling the client's model to follow this path:

```
list_operations     what operations exist?
get_example         copy wiring from a real workflow
get_operations      exact parameter schemas
inspect_dataset     real columns, real values
run_workflow        preview against real data (nothing saved)
validate_workflow   optional draft check (the run tools validate on their own)
save_workflow       persist as a draft
run_backtest        validates + simulates, returns a backtest_id immediately
deploy_index        register a live index (confirm=true)
```

Operation names, dataset ids, column names and filter values are always looked up, never guessed.

## Notes

- Stateless streamable HTTP: every request is self-contained, `POST` only (`GET`/`DELETE` return `405`), JSON responses returned directly — no SSE stream required.
- Preview runs cache their outputs for two hours so `inspect_run` and `get_column_values` work across calls.
- `run_backtest` and `deploy_index` never hold the connection open: they validate synchronously, then return a `backtest_id` (and, for deploys, the pending `index_id`) immediately; poll `get_backtest` for the result — it absorbs part of the wait server-side, so polling back-to-back is fine.

## Support

Questions, higher rate limits, or anything odd: support@indexone.io