> For the complete documentation index, see [llms.txt](https://docs.koinju.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.koinju.io/mcp-server.md).

# MCP server

Koinju runs a hosted [Model Context Protocol](https://modelcontextprotocol.io) server at `https://mcp.koinju.io/mcp`. It gives an AI coding agent — Claude Code, Cursor, VS Code, Codex — direct tools over the market data, so it can look up an instrument and pull candles, trades, funding or an option chain without you writing the request.

Since it uses the same api key as the rest api it shares the same limits.

## Connect

{% tabs %}
{% tab title="Claude Code" %}
{% code overflow="wrap" %}

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

{% endcode %}
{% endtab %}

{% tab title="Codex" %}
`codex mcp add` cannot set a header, so write it into `~/.codex/config.toml`:

```toml
[mcp_servers.koinju]
url = "https://mcp.koinju.io/mcp"
http_headers = { "x-api-key" = "YOUR_API_KEY" }
```

{% endtab %}

{% tab title="Cursor" %}
`~/.cursor/mcp.json`, or `.cursor/mcp.json` for one project:

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

{% endtab %}

{% tab title="VS Code" %}
`.vscode/mcp.json`. The key is `servers`, not `mcpServers`, and the type is required:

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

{% endtab %}

{% tab title="Gemini CLI" %}
{% code overflow="wrap" %}

```bash
gemini mcp add --transport http --header "x-api-key: YOUR_API_KEY" koinju https://mcp.koinju.io/mcp
```

{% endcode %}

Add `-s user` to register it for every project rather than the current one.
{% endtab %}

{% tab title="Windsurf" %}
`~/.codeium/windsurf/mcp_config.json`:

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

{% endtab %}

{% tab title="Cline" %}
Cline panel → **MCP Servers** → **Configure MCP Servers**. Without the type, Cline falls back to the legacy SSE transport:

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

{% endtab %}
{% endtabs %}

Your key is on your [dataroom](https://dataroom.koinju.io) credentials page, with the command above already filled in. Don't have one? Sign up at [koinju.io/pricing](https://koinju.io/pricing).

## First prompt

Paste this into your agent once the server is connected:

{% code overflow="wrap" %}

```
Using the Koinju MCP tools, fetch daily candles for binance BTC-USDT and binance ETH-USDT over the last 30 days. Compute daily log returns from the close prices, report the Pearson correlation for the month, and plot both normalised price series with a 7-day rolling correlation underneath. Save the chart as btc_eth_correlation.png.
```

{% endcode %}

## Together with the agent skill

The [agent skill](/ai-agent-skill.md) and this server solve different halves. The skill teaches your agent the schema, the auth and the query patterns; the server hands it tools it can call. Install both: the skill makes the agent fluent in Koinju, the server saves it from writing HTTP by hand.