加密数据 MCP 服务器

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

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/chatgpt 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
• POST /mcp/chatgpt — the same endpoint with the ChatGPT tool profile, which leaves out third-party news, web, signal, and X content tools (see src/profiles.ts)
• GET /healthz — deployment health check
• GET /.well-known/oauth-protected-resource — OAuth resource metadata (RFC 9728); returns 404 until SURF_OAUTH_AUTHORIZATION_SERVER is configured
• GET /.well-known/oauth-authorization-server — the authorization server's RFC 8414 metadata, relayed from the issuer
• GET /.well-known/openid-configuration — the authorization server's OpenID Connect discovery document, relayed from the issuer; hosts that enforce workspace domain restrictions (ChatGPT Enterprise/Team) read the userinfo_endpoint and the openid/email scopes from here

Authentication

Each HTTP request's Authorization header is forwarded verbatim to the Surf data API, so callers presenting their own Surf API key (or a Surf-issued OAuth token, once available) are billed and rate-limited on their own account. Resolution order per request:

1. The incoming Authorization header, forwarded as-is
2. The deployment's SURF_API_KEY service key (Bearer scheme)
3. Anonymous — the Surf API's per-IP allowance applies

Environment variables for OAuth discovery and login:

Deployment modes:

Scopes: data:read is the base scope of every grant. Requesting openid additionally returns an ID token and enables the userinfo endpoint; email releases the account's verified email through both. When registering the server with a host that supports domain restrictions, request openid email (the data scope is implied).

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, api/mcp-chatgpt.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