# MCP Server

Connect Arkham to Claude, Claude Code, or Codex, then ask questions about on-chain activity in plain English. The assistant looks up the answer in Arkham for you.

  **Server URL:** `https://mcp.arkm.com/mcp`

## What You'll Need

- An **Arkham API key**. You need an API plan or trial first (see [Getting Access](/getting-started/access)), then create a key on the [API Dashboard](https://arkm.com/api-dashboard?tab=api-keys).
- An AI assistant: the **Claude app** ([desktop](https://claude.ai/download), web, or mobile), **Claude Code**, or **Codex**.

Nothing to install. Arkham hosts the server.

## Set Up in Claude

1. In Claude, go to **Customize → Connectors** and click **Add custom connector**.
2. Name it _Arkham_ and paste the server URL: `https://mcp.arkm.com/mcp`
3. Claude checks the server and shows **Couldn't check the server**. This is expected: click **Continue anyway**.
4. Under **Authentication**, choose **No sign-in**.
5. Open **Request headers**, pick `authorization`, and enter `Bearer YOUR_API_KEY`.
6. Click **Add**.

That's it. The connector is saved to your Claude account, not your computer, so Arkham is available in every Claude chat on every device you sign in to: desktop, web, and mobile.

::: tip
Don't see **Request headers**? That option isn't available on every Claude plan yet. Use Claude Code or Codex below instead. On a Team or Enterprise plan, only a workspace Owner can add the connector, and everyone in the workspace then shares that one API key and its credits.
:::

## Set Up in Claude Code

Run this once in your terminal:

```bash
claude mcp add --transport http arkham https://mcp.arkm.com/mcp --header "Authorization: Bearer YOUR_API_KEY" --scope user
```

This is saved on the computer you run it on, for all your projects there. Repeat it on each computer where you use Claude Code.

## Set Up in Codex

On macOS or Linux, save your API key as an environment variable, then run this once in your terminal:

```bash
export ARKHAM_API_KEY="YOUR_API_KEY"
codex mcp add arkham --url https://mcp.arkm.com/mcp --bearer-token-env-var ARKHAM_API_KEY
```

Add the `export` line to your shell profile (for example `~/.zshrc`) so the key is there next time. Like Claude Code, this is saved on the computer you run it on.

## Try It

Open a new chat and ask:

> _"Which chains does Arkham support?"_

> _"Who are the top 10 counterparties of Binance on Ethereum over the last 7 days?"_

The assistant picks the right Arkham lookup and shows you the result.

::: info Credits
Most lookups use API credits, the same as calling the API directly. A few, such as the list of supported chains, are free. See [Credit Pricing](/usage/credit-pricing).
:::

## MCP or the API?

Both use the same data, API key, and credits. Pick by the size of the job.

| Use MCP for | Use the [API](#api-reference) for |
| --- | --- |
| Questions and quick lookups in a chat | Large exports and backfills |
| Exploring an address, entity, or token | Paging through thousands of rows |
| Small result sets, such as a top 10 or the last day | Live streams (WebSocket) |
| No code | Scripts, apps, and scheduled jobs |

MCP answers are capped at about 4 MB each. A request that returns more fails, and still uses its credits, so keep MCP requests small and use the API for anything big.

## If Something's Not Working

| Problem | Fix |
| --- | --- |
| Arkham doesn't show up, or won't connect (Claude, Claude Code) | The key header is missing or malformed. It must be `Bearer ` (with a space) followed by your key. Check the URL is `https://mcp.arkm.com/mcp`, then restart the app. In Claude Code, run `claude mcp list` to check the connection. |
| Arkham won't connect (Codex) | `ARKHAM_API_KEY` must hold the key alone, without `Bearer `, and be set in the terminal you start Codex from. |
| An "Attention Required" page appears | The request reached Arkham without a valid key header. Fix the header as above. |
| Arkham connects, but every question fails with `401` and "Could not verify API Key" | The key itself is wrong. Check it for typos and extra spaces, or create a new one. |
| "API response exceeds 4 MiB; narrow the query or reduce its limit" | The answer is too large. Ask for less at once, for example a shorter time range or fewer results. |
| A question times out with `504` | Most lookups have 60 seconds to finish. Ask a narrower question: a shorter time range, one chain, or fewer results. |

::: warning Keep your key private
Don't share your API key or paste it into a chat. Anyone with it can use your credits.
:::