Connecting to Nansen MCP

The Nansen MCP server provides AI assistants with access to comprehensive blockchain analytics through a secure API. This guide covers how to connect to Nansen MCP.

Grok uses a different URL and OAuth — not an API key. Follow Grok (OAuth) and https://mcp.nansen.ai/ra/connector-curated/mcp. Do not paste a NANSEN-API-KEY into Grok.

Prerequisites

Before connecting, you'll need:

1. Nansen API Key: Get yours at https://app.nansen.ai/auth/agent-setup

2. npx: Only needed for the "Other MCP Clients" section below, which bridges through mcp-remote. It ships with Node.js — no separate install. Claude Desktop, Claude Code, and Cursor connect directly and do not need it.

Installation Guide

1. Claude Desktop (One-Click Install; Claude Desktop Required)

The easiest way to get started with Nansen MCP. Double-click the downloaded .dxt file to configure automatically.

Quick Install Link

The bundle is versioned independently of this page, so its embedded connection settings may lag the values documented below. Prefer the bundle for a working install; use this page as the reference for the current endpoint and header.

2. Claude Code (Terminal Integration)

Connect Nansen MCP through your terminal:

claude mcp add --transport http nansen https://mcp.nansen.ai/ra/mcp --header "NANSEN-API-KEY: YOUR_API_KEY_HERE"

3. Cursor IDE

Cursor supports the Nansen MCP server directly through its native url and headers configuration. Create ~/.cursor/mcp.json (on Windows, %USERPROFILE%\.cursor\mcp.json) and replace YOUR_API_KEY_HERE before saving:

{
  "mcpServers": {
    "nansen": {
      "url": "https://mcp.nansen.ai/ra/mcp",
      "headers": {
        "NANSEN-API-KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

If mcp.json already exists, add only the nansen entry under its existing mcpServers object. On macOS/Linux, run chmod 600 ~/.cursor/mcp.json because the file contains an API key — re-check the mode after editing servers through the Cursor UI, since a rewrite can reset it. Restart Cursor (or toggle the server in Cursor Settings > MCP) to pick up the change, then follow Verifying your connection below.

If your Cursor build does not support the url field, use the mcp-remote bridge from the "Other MCP Clients" section instead.

Cursor install deep links (cursor://anysphere.cursor-deeplink/mcp/install?...) are no longer published. Cursor saves the link's decoded configuration as-is, so the link could only ever ship a placeholder key that you still had to find and replace inside an opaque payload — and a link carrying a real key would put that key in your clipboard history, chat logs, and link previews. The explicit configuration above replaces it.

4. Other MCP Clients

Integration example for various other tools supporting MCPs

Server configuration:

• Server: https://mcp.nansen.ai/ra/mcp

• HTTP header: NANSEN-API-KEY: YOUR_API_KEY_HERE

• Transport: mcp-remote

Clients that speak streamable HTTP natively should use the url + headers form shown in the Cursor section above. Only stdio-only clients need the mcp-remote bridge below.

{
  "mcpServers": {
    "nansen": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.2.1",
        "https://mcp.nansen.ai/ra/mcp",
        "--header",
        "NANSEN-API-KEY:${NANSEN_API_KEY}"
      ],
      "env": {
        "NANSEN_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

mcp-remote substitutes ${NANSEN_API_KEY} in the header from the environment, so the key lives in env rather than in the argument list — prefer that form, since arguments are visible in process listings. If the variable is unset the header is sent empty and every tool call fails, so keep the env entry.

--header and its value must be two separate entries in args. Whitespace after the colon is trimmed, so NANSEN-API-KEY: ${NANSEN_API_KEY} works too, but the value must contain both the header name and the key.

mcp-remote is pinned to an exact version rather than @latest because the bridge handles your API key on every request, and npx would otherwise pull a new release automatically the first time you run it. 0.2.1 is the current release at the time of writing and the version these instructions are tested against. Bumping it is safe and encouraged — check the latest version, review what changed, and update this pin.

NPX example:

export NANSEN_API_KEY=YOUR_API_KEY_HERE
npx -y mcp-remote@0.2.1 https://mcp.nansen.ai/ra/mcp \
  --header 'NANSEN-API-KEY:${NANSEN_API_KEY}'

Verifying your connection

Your client showing Nansen tools in its list does not mean authentication works: the server answers initialize and tools/list without any API key at all. Only a tool call is authenticated, so verify with one.

In your client: ask it for token information for a well-known token — for example, "use Nansen to get token info for USDT on ethereum". Real figures mean the key works. An error mentioning Invalid API key or NANSEN-API-KEY header is required means the key never reached the server; re-check the header name and value in your configuration, then restart the client.

From a terminal, to test the key independently of any client:

curl -s -X POST https://mcp.nansen.ai/ra/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "NANSEN-API-KEY: YOUR_API_KEY_HERE" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"token_info","arguments":{"request":{"chain":"ethereum","token_address":"0xdAC17F958D2ee523a2206206994597C13D831ec7"}}}}'

Read the response body, not the HTTP status — an invalid key still returns 200, with the failure reported as "isError": true inside the result. This call consumes credits, like any other tool call.

The Accept header above is required when calling the server directly with curl. MCP clients set it for you.

Authentication

⚠️ Nansen MCP uses the same API as your regular API keys. Ensure you have sufficient credits for your usage.