# TimechainIndex MCP guide

Connect your AI assistant to Bitcoin data from TimechainIndex. Ask for exchange balances, ETF holdings, network statistics, UTXO distributions, address rankings, or Bitcoin labels, and the assistant retrieves data through MCP tools.

## Start here

- Server URL: `https://api.timechainindex.com/mcp/` (keep the trailing slash).
- Connection: remote Streamable HTTP.
- Authentication header: `X-API-Key` with your TimechainIndex API key.
- Requirements: a valid, unexpired key with an active TimechainIndex subscription and an MCP-compatible AI client.
- Bitcoin labels and label timestamps require Professional or Enterprise access and remaining label quota.

Configure your key in the client's credential settings or environment. You do not need to paste it into chat. A TimechainIndex key is separate from any OpenAI or Anthropic API key. AI-client subscriptions and administrator restrictions may also apply.

## Choose your AI tool

| Client | Connection method |
| --- | --- |
| VS Code / GitHub Copilot | HTTP server with a password input or environment-backed header |
| Cursor | HTTP server with an environment-backed header |
| Claude Code | HTTP configuration with an environment-backed header |
| Claude web / Desktop remote connectors | Custom connector with Request headers, where available |
| Codex CLI / IDE extension | HTTP server in Codex configuration |
| ChatGPT custom MCP apps | Current authentication requires an additional integration; see the ChatGPT section |

These instructions were checked against official client documentation on October 9, 2026. Menus and account availability can change. VS Code hosted connectivity has been verified for this server; the other configurations follow vendor documentation and have not been tested here.

## VS Code and GitHub Copilot

Create or merge this into `.vscode/mcp.json` in your workspace. Keep any existing server entries.

```json
{
  "inputs": [
    {
      "id": "timechainKey",
      "type": "promptString",
      "description": "Your TimechainIndex API key",
      "password": true
    }
  ],
  "servers": {
    "timechainindex": {
      "type": "http",
      "url": "https://api.timechainindex.com/mcp/",
      "headers": { "X-API-Key": "${input:timechainKey}" }
    }
  }
}
```

1. Open the workspace in VS Code.
2. Run `MCP: List Servers` from the Command Palette.
3. Start `timechainindex`, accept the server trust prompt, and enter your key when prompted.
4. Open Copilot Chat in Agent mode and send the first test prompt below.

VS Code can remember the input, so it may not ask for a key on every request. Some newer Agent Host flows do not forward interactive input configurations. If your flow cannot see the server, use `"X-API-Key": "${env:TIMECHAIN_API_KEY}"` instead, and launch VS Code with that environment variable available. Restart the MCP server after configuration changes. [Official VS Code configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

## Cursor

Set `TIMECHAIN_API_KEY` in the environment inherited by Cursor. Create `.cursor/mcp.json` for a project, or `~/.cursor/mcp.json` for your user:

```json
{
  "mcpServers": {
    "timechainindex": {
      "url": "https://api.timechainindex.com/mcp/",
      "headers": { "X-API-Key": "${env:TIMECHAIN_API_KEY}" }
    }
  }
}
```

Restart Cursor after changing its environment. Check the MCP server status in Cursor settings, enable the server, and use Agent chat. Remote configurations use the application's environment; Cursor's `envFile` option is for local stdio servers. [Official Cursor MCP documentation](https://cursor.com/docs/mcp).

## Claude Code

Set `TIMECHAIN_API_KEY` in Claude Code's environment. Add this entry to a project `.mcp.json`, merging any existing entries:

```json
{
  "mcpServers": {
    "timechainindex": {
      "type": "http",
      "url": "https://api.timechainindex.com/mcp/",
      "headers": { "X-API-Key": "${TIMECHAIN_API_KEY}" }
    }
  }
}
```

Start Claude Code in that project, approve the project MCP configuration if prompted, and use `/mcp` to check the connection. Claude Code uses `${TIMECHAIN_API_KEY}` here, while Cursor uses `${env:TIMECHAIN_API_KEY}`. Run the first test prompt below. [Official Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).

## Claude web and Desktop remote connectors

Where your account exposes custom connectors and Request headers:

1. Open `Customize > Connectors` and choose `Add custom connector`.
2. Name it `TimechainIndex` and enter `https://api.timechainindex.com/mcp/`.
3. For this API-key integration, select `No sign in` for the OAuth sign-in setting.
4. Under Request headers, set the header name to `X-API-Key` and its value to your key.
5. Add the connector and enable it for your conversation.

The key header still authenticates every request; `No sign in` only means no OAuth login. If Request headers is unavailable in your account, use Claude Code or another compatible client instead. For a shared Team/Enterprise connector, the fixed credential is shared by its users; its account usage and quotas are shared too. [Official Claude connector instructions](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

## Codex CLI and IDE extension

Set `TIMECHAIN_API_KEY` in the environment inherited by Codex. Merge this entry into your Codex `~/.codex/config.toml`:

```toml
[mcp_servers.timechainindex]
url = "https://api.timechainindex.com/mcp/"
env_http_headers = { "X-API-Key" = "TIMECHAIN_API_KEY" }
```

Restart the CLI or IDE extension so it receives the environment variable. In the CLI, use `codex mcp list` to inspect configuration, then ask Codex to call the first test tool. A configured entry alone does not prove a successful connection; check the tool result. MCP configurations can be restricted by workspace or organization policy. [Official OpenAI MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

## ChatGPT custom MCP apps

This server currently requires `X-API-Key` on hosted requests and does not implement OAuth. The documented ChatGPT custom MCP flow offers OAuth or no authentication, rather than this server's custom API-key header. Direct setup through that flow is not currently supported by this deployment. Do not choose anonymous access or put a key in the URL to work around it.

To support that flow, TimechainIndex needs a compatible per-user authentication integration, such as OAuth, preserving subscription and quota checks. Until then, use VS Code, Cursor, Claude Code, Codex, or Claude's Request headers option where available. This concerns the ChatGPT app connector, not OpenAI API integrations. [Official ChatGPT custom MCP instructions](https://developers.openai.com/api/docs/guides/custom-mcp-server).

## Set an environment variable

For clients configured with environment-backed headers, make `TIMECHAIN_API_KEY` available to the application process before launching it. Here is a PowerShell session example that avoids typing the secret in shell history:

```powershell
$timechainSecret = Read-Host "TimechainIndex API key" -AsSecureString
$env:TIMECHAIN_API_KEY = [System.Net.NetworkCredential]::new('', $timechainSecret).Password
# Launch your client from this terminal, for example:
cursor .
```

Close already-running instances first so the new process inherits the variable. This variable lasts for the current terminal session; environment variables are configuration, not an encrypted credential vault. Use a client's password prompt or supported credential storage when available. Do not commit real keys to configuration files.

## First successful requests

Send these prompts in your connected AI client:

```text
Call timechainindex list_available_endpoints with limit 5.
```

```text
Call timechainindex get_etf_summary with limit 2.
```

Expand the assistant's activity and look for the actual MCP tool call. Reading a README, running terminal commands, or repeating previous chat answers does not prove a live MCP call. Discovery lists supported datasets; the ETF request verifies protected data retrieval and consumes normal API usage.

## Available tools

| Tool | Purpose and inputs |
| --- | --- |
| `list_available_endpoints` | Discover dataset IDs, categories, required parameters, and access rules; optional `category`, `search`, `limit`, `offset` |
| `get_api_data` | Retrieve any catalog dataset using `dataset`, optional `params`, `limit`, `offset` |
| `get_utxo_distribution` | `blockheight` and `grouping`: value, age, epoch, year |
| `get_network_stats` | `period`: daily, monthly, yearly, epoch |
| `get_etf_summary` | Latest US Bitcoin ETF summary |
| `lookup_bitcoin_labels` | An `addresses` array of 1–100 Bitcoin addresses |
| `bitcoin_labels_timestamp` | Labels update metadata; no inputs |

The current catalog has 89 datasets. Ask the discovery tool for the current count and IDs. The downloadable [dataset catalog](mcp-datasets.json) describes the supported routes; it is not a live health check.

| Category | Data |
| --- | --- |
| `utxos` | Snapshot heights; distributions; coinbase outputs; spent-output age; profit/loss |
| `addresses` | Snapshot heights and balance distributions |
| `entities` | Exchange/tag history; entity balances; address/UTXO breakdowns; top addresses; chart data |
| `network` | Block frequency; daily/monthly/yearly/epoch statistics; mining pools |
| `miners` | Public mining-company holdings and changes in BTC/USD |
| `etfs` | Holdings, flows, net flows, summaries, supply comparisons, quarterly 13F filings |
| `miscellaneous` | BTC/USD prices, US/Japan debt, client-label tiers, update information |
| `labels` | Address tags, entities, balances, UTXO counts, update metadata |
| `public` | API status and database comparison |

Quarterly filing routes currently cover 2024 Q1 through 2026 Q2. Labels are TimechainIndex's classifications. Data freshness varies by dataset; request available timestamps rather than assuming every dataset is live or has the same snapshot date.

## Examples you can ask

```text
Call timechainindex get_api_data with dataset top_add_by_amount and limit 10.
```

```text
Call timechainindex list_available_endpoints with category entities and limit 100.
```

```text
Call timechainindex get_api_data with dataset entitysummary_addresses_set,
params {"entity":"Binance"}, and limit 10.
```

```text
Call timechainindex get_api_data with dataset 2026q2_companysummary and limit 5.
```

For a UTXO snapshot, first request `utxos_all_height_directory` and choose an available height. For labels, provide the actual addresses to `lookup_bitcoin_labels`. To rank by UTXO count instead of balance, use `top_add_by_utxos`.

## Pagination, access, and billing

Paged tools default to 100 rows and allow 1–500. Use `offset` and follow `nextOffset` to retrieve another page. The tools preserve upstream ordering; `limit: 10` does not itself sort a dataset. Each page refetches the API response, so it can count as another API request and may reflect a newer snapshot.

All hosted MCP requests require an active key, including catalog discovery and access to public datasets. The underlying public REST routes retain their public access. The local stdio adapter can discover the catalog without a key.

Protected data calls use your key and the API's existing billing rules. Basic data tracks successful requests in `apiusedbasic`. Label lookups require Professional or Enterprise access, remaining label quota, and charge according to new unique returned addresses. Label timestamps also undergo the API's plan/quota checks. Reading data can consume quota even if a result is later too large for the assistant. No arbitrary SQL, URL fetching, or write tool is exposed.

Results are bounded by a 15-second upstream timeout, an 8 MiB API-response cap, and a 256 KiB tool-result cap. Pagination slices the full response after fetching it; it does not reduce the backend query or upstream payload. Smaller row limits help with tool-result size, but oversized upstream datasets need backend filtering.

## Troubleshooting

| Symptom | What to check |
| --- | --- |
| 401 / Invalid API key | Key belongs to TimechainIndex, is configured, and still exists; restart after replacing it |
| 403 / Active subscription required | Account subscription is active |
| Labels denied with 403 | Plan is Professional/Enterprise; quota also permits the returned addresses |
| 410 / API key expired | Renew or replace the expired key |
| 429 / API quota exceeded | Remaining label quota; contact TimechainIndex if needed |
| 503 / Authorization temporarily unavailable | Server-side key validation is unavailable; retry later |
| Redirect rejected | Use `https://api.timechainindex.com/mcp/` with the trailing slash |
| Browser displays API key required | Expected: browsers do not automatically send your client credential header |
| Authenticated GET returns 405 | Expected: this endpoint uses MCP POST messages |
| No tools visible | Restart/reload the client, confirm server status, and check client/admin tool policies |
| Tool returns timeout or size error | Retry with a smaller result or narrower dataset; upstream limits may require an API change |

Keep keys out of chat, screenshots, URLs, and source control. An assistant remembering a previous answer does not mean it bypassed authentication. Inspect a fresh tool call when testing access.

## Optional local connection

If you have the repository, Node.js 22+, and installed dependencies, the local adapter is also available. Configure `mcp/.env` using `mcp/.env.example`, then configure your client to launch `node` with the absolute path to `mcp/server.js`. It talks over stdio and waits for protocol messages; typing `hi` in its terminal does not start a conversation. See the repository's `mcp/README.md` for setup. Hosted users do not need Node.js or a local checkout.