surf-mcp

MCP server for the Surf crypto data API. Dynamically generates tools from the OpenAPI spec across market data, wallets, social, on-chain queries, and more. It supports stdio for local clients and Streamable HTTP for hosted ChatGPT/Codex integrations.

Quick start

Add to your MCP client config — no clone or install needed:

{
  "mcpServers": {
    "surf": {
      "type": "http",
      "url": "https://mcp.asksurf.ai/mcp"
    }
  }
}

To run the stdio package locally instead:

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

Prerequisites

• Node.js 20+ or Bun

• Optional: a Surf API key (get one here) for account credits and higher limits. Without a key, Surf's anonymous per-IP allowance applies.

Config file locations

• 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

Related MCP server: agentpulse-mcp

Claude Code plugin

This repository is also a Claude Code marketplace. Install the Surf plugin with:

claude plugin marketplace add asksurf-ai/surf-mcp
claude plugin install surf@surf

The plugin connects to the hosted anonymous beta. Usage is limited by Surf's anonymous allowance; production deployments should use a dedicated, rate-limited service key or OAuth 2.1.

ChatGPT and Codex plugin

The repository contains a Codex/ChatGPT plugin package under plugins/surf, a Claude package under claude-plugin, and repo marketplaces for both hosts. The two thin package directories are separate because the current hosts validate different .mcp.json root shapes; both connect to the hosted MCP endpoint. Codex can add its marketplace directly:

codex plugin marketplace add asksurf-ai/surf-mcp

Register https://mcp.asksurf.ai/mcp in ChatGPT Plugins. See docs/chatgpt-plugin-submission.md for the submission checklist.

Streamable HTTP deployment

Run the hosted transport locally:

bun run start:http

The server exposes:

• POST /mcp — stateless MCP Streamable HTTP endpoint

• GET /healthz — deployment health check

Build and run the included container:

docker build -t surf-mcp .
docker run --rm -p 3000:3000 -e SURF_API_KEY=your-service-api-key surf-mcp

The limited beta is live at https://mcp.asksurf.ai/mcp. For higher capacity, keep a dedicated, rate-limited SURF_API_KEY in the host's secret manager; never put it in plugin manifests or client-visible responses.

The included Vercel Functions adapter exposes the same endpoints from api/mcp.ts and api/healthz.ts. Deploy it to a Vercel project when a serverless beta is preferable to the container image.

Tools

The server currently exposes 15 tools, one per API domain. Each tool accepts a command and optional params; the exact commands update automatically with the Surf OpenAPI specification:

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 ..." } })
"Surf's token of the day"      → surf_signal({ command: "token-of-the-day" })

How it works

On startup, the server:

1. Fetches the OpenAPI spec from https://api.asksurf.ai/gateway/openapi.json (cached for 24h)

2. Groups all operations by their API tag

3. Registers one MCP tool per tag with auto-generated descriptions and command enums

4. Routes tool calls to the Surf API with native HTTP fetch and optional bearer authentication

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

Example: AI agent

The repo includes a simple agent that connects Claude to surf-mcp tools in an agentic loop. See examples/agent.ts.

ANTHROPIC_API_KEY=your-key SURF_API_KEY=your-key bun run examples/agent.ts "What's the BTC price and fear & greed index?"

Development

git clone https://github.com/asksurf-ai/surf-mcp.git
cd surf-mcp
bun install
bun run start                # Run the server
bun run start:http           # Run Streamable HTTP on :3000
bun run typecheck            # Type check

License

MIT