MCP Server

The Surf MCP server gives any MCP-compatible AI client (Claude Desktop, Cursor, Windsurf, etc.) direct access to crypto data. It dynamically generates tools from the OpenAPI spec — no code to write, no endpoints to memorize.

Quick Start

Add to your MCP client config:

{
  "mcpServers": {
    "surf": {
      "command": "npx",
      "args": ["-y", "@surf-ai/surf-mcp"],
      "env": {
        "SURF_API_KEY": "your-api-key"
      }
    }
  }
}

Or with Bun (faster startup):

{
  "mcpServers": {
    "surf": {
      "command": "bunx",
      "args": ["@surf-ai/surf-mcp"],
      "env": {
        "SURF_API_KEY": "your-api-key"
      }
    }
  }
}

Prerequisites

A Surf API key (get one here)
Node.js 20+ or Bun

Config File Locations

Client	Path
Claude Code	`.mcp.json` in project root or `~/.claude.json`
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
Cursor	MCP settings in the IDE

Tools

The server exposes 12 tools, one per API domain:

Tool	Commands	Description
`surf_market`	`price`, `ranking`, `etf`, `futures`, `options`, `fear-greed`, `liquidation-*`, `onchain-indicator`, `price-indicator`	Market overview, rankings, indicators, ETF flows
`surf_exchange`	`depth`, `klines`, `funding-history`, `perp`, `price`, `markets`, `long-short-ratio`	Live exchange data from Binance, OKX, Bybit, etc.
`surf_wallet`	`detail`, `transfers`, `history`, `net-worth`, `protocols`, `labels-batch`	Wallet balances, transfers, DeFi positions
`surf_token`	`holders`, `dex-trades`, `transfers`, `tokenomics`	Token holder analysis, DEX trades, unlocks
`surf_social`	`detail`, `user`, `user-posts`, `tweets`, `mindshare`, `ranking`, `smart-followers-history`	X (Twitter) social signals and sentiment
`surf_project`	`detail`, `defi-metrics`, `defi-ranking`	Project profiles, DeFi TVL/fees/revenue
`surf_onchain`	`sql`, `tx`, `gas-price`, `schema`, `bridge-ranking`, `yield-ranking`	On-chain SQL queries, tx lookup, gas prices
`surf_search`	`project`, `wallet`, `news`, `web`, `fund`, `polymarket`, `kalshi`, `airdrop`	Unified search across all data types
`surf_prediction_market`	`kalshi-`, `polymarket-`, `category-metrics`	Polymarket and Kalshi prediction markets
`surf_fund`	`detail`, `portfolio`, `ranking`	Crypto VC fund profiles and portfolios
`surf_news`	`feed`, `detail`	Crypto news from major outlets
`surf_web`	`fetch`	Fetch any URL as clean markdown

Usage Examples

Once configured, your AI assistant can use the tools directly:

"What's the BTC price?"        → surf_market({ command: "price", params: { symbol: "BTC" } })
"Check vitalik's wallet"       → surf_wallet({ command: "detail", params: { address: "vitalik.eth" } })
"Search for DeFi projects"     → surf_search({ command: "project", params: { q: "defi lending" } })
"Run an on-chain SQL query"    → surf_onchain({ command: "sql", params: { sql: "SELECT ..." } })
"ETH social sentiment"         → surf_social({ command: "detail", params: { q: "ethereum" } })

How It Works

On startup, the server:

Fetches the OpenAPI spec from https://api.ask.surf/gateway/openapi.json (cached for 24h)
Groups all operations by their API tag
Registers one MCP tool per tag with auto-generated descriptions and command enums
Routes tool calls through @surf-ai/sdk for HTTP transport and auth

The server automatically picks up new API endpoints when the spec is updated — just restart.

Surf Skill vs MCP Server

	Surf Skill	MCP Server
Install	`npx skills add asksurf-ai/surf-skills`	JSON config in MCP settings
Works with	Claude Code, Codex	Claude Desktop, Cursor, Windsurf, any MCP client
Auth	`SURF_API_KEY` env var	`SURF_API_KEY` env var
How it works	Teaches agent to use CLI	Exposes tools via MCP protocol
Best for	Coding agents	General-purpose AI assistants

Resources

npm: @surf-ai/surf-mcp
GitHub: asksurf-ai/surf-mcp
API Docs: docs.asksurf.ai

API Reference

​MCP Server

​Quick Start

​Prerequisites

​Config File Locations

​Tools

​Usage Examples

​How It Works

​Surf Skill vs MCP Server

​Resources