> 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 agent nine tools over Koinju's market data: `run_sql`, which runs a read-only SQL statement, and eight REST tools that look up a market and pull candles, trades, funding rates, a volatility index or an option chain. The agent picks the tool and writes the request, so you do not have to.

You sign in with your Koinju account, in the browser. There is no API key to paste: every tool runs with the credentials your account already has.

## What the tools run as

* `run_sql` runs each statement with your own SQL login, the one on your [dataroom](https://dataroom.koinju.io) credentials page. It reads the same tables as [direct SQL](/how-to-connect.md), and your plan's [SQL limits](/pricing.md#sql-limits) apply to it, shared with everything else you run on that login.
* `get_ohlcv`, `get_trades`, `get_funding_rate`, `get_volatility_index`, `get_option_chain`, `get_option_smile` and `get_option_matrix` call the REST API with your own API key, from the same credentials page. Each call is one REST request, so your plan's [REST quota](/pricing.md#rest-api-limits) applies to it, shared with the REST calls you make yourself. When the day's quota is used, the tool answers `Daily quota reached for your key. Higher quotas: https://koinju.io/pricing`.
* `find_markets` reads the public market lists with no key, so it spends none of your quota. It returns the exact `exchange` and `market_symbol` the data tools take.

For more than a few thousand rows `run_sql` is the better tool, as [REST vs SQL](/pricing.md#rest-vs-sql) explains.

## What `run_sql` answers

* Only read-only statements run: `SELECT`, `WITH`, `SHOW`, `DESCRIBE`, `EXISTS` and `EXPLAIN`.
* The answer is ClickHouse's CSV followed by a line `N rows`. An answer longer than 100,000 characters is refused whole, never cut: aggregate it, add a `LIMIT`, or use direct SQL.
* You can run 2 statements at once, and the same statement is refused when it is sent more than 5 times in a minute.

## Connect

Enter the URL exactly as `https://mcp.koinju.io/mcp`, with no trailing slash. The client opens your browser the first time: log in with your Koinju account, check the client and the address named on the page, and choose **Allow**. Your Koinju account is the email and password you use to sign in to the [dataroom](https://dataroom.koinju.io), the password you set from the welcome email.

{% tabs %}
{% tab title="Claude" %}
In claude.ai or Claude Desktop, open **Customize** > **Connectors**, choose **+ Add** > **Add custom connector**, give it a name, paste the URL and sign in.

On a Team or Enterprise plan an Owner adds it under **Organization settings** > **Connectors**, and members then connect it under **Customize** > **Connectors**.
{% endtab %}

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

```bash
claude mcp add --transport http koinju https://mcp.koinju.io/mcp
```

{% endcode %}

Then run `/mcp` inside Claude Code, choose **koinju** and sign in. From a shell, `claude mcp login koinju` does the same.
{% endtab %}

{% tab title="Codex" %}

```bash
codex mcp add koinju --url https://mcp.koinju.io/mcp
codex mcp login koinju
```

The first command writes this entry to `~/.codex/config.toml`:

```toml
[mcp_servers.koinju]
url = "https://mcp.koinju.io/mcp"
```

{% endtab %}

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

```json
{
  "mcpServers": {
    "koinju": {
      "url": "https://mcp.koinju.io/mcp"
    }
  }
}
```

Cursor opens your browser to sign in when it connects.
{% 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"
    }
  }
}
```

VS Code asks you to sign in when it starts the server.
{% endtab %}

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

```bash
gemini mcp add --transport http koinju https://mcp.koinju.io/mcp
```

{% endcode %}

Add `-s user` to register it for every project rather than the current one. Gemini starts the sign-in when the server asks for it, and `/mcp auth koinju` starts it by hand. It needs a browser on the same machine.
{% endtab %}
{% endtabs %}

Other MCP clients that support OAuth sign-in connect with the same URL.

## Signing in

* The browser shows Koinju's login, then a page that names the client, the address the sign-in returns to and your email. It asks again for every connection: choose **Deny** if you did not start it.
* The client renews its access every hour on its own, and stays connected as long as you use it at least once in 30 days. Remove the connector from the client to disconnect it.
* If your SQL login changes, for example after you re-subscribe, the next `run_sql` call answers `Your SQL login changed; call again to sign in.` and the client offers to connect again.
* If your API key is refused, the seven data tools answer `Your Koinju API key was refused; your plan may have ended. Plans: https://koinju.io/pricing`. `run_sql` and `find_markets` keep working.
* An account without a SQL login, such as a cancelled one, is sent to [koinju.io/pricing](https://koinju.io/pricing).
* A client set up with the old `x-api-key` header: remove the header and sign in. The server ignores a key sent by the client.

## First prompt

Paste this into your agent once the server is connected:

{% code overflow="wrap" %}

```
Using the Koinju MCP server, 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 requests or running the SQL by hand.