MCP Server

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

There are two ways to run it:

The hosted endpoint is the recommended path.

Connect

Pick whichever your client supports. All three work against the same hosted endpoint.

Sign in with your Surf account (OAuth)

Clients that implement MCP authorization can log you in through the browser — no key to copy, and usage bills to your own account.

In Claude Code:

claude mcp add --transport http --scope user surf https://mcp.asksurf.ai/mcp

Then start a new session, run /mcp, select surf, and choose Authenticate. Your browser opens the Surf authorization page; sign in, approve the request, and the client is connected. The grant is read-only (data:read) — it can query data but cannot manage your API keys, billing, or account settings, and you can revoke it at any time.

Clients without OAuth support fall back to an API key, below.

API key

Works everywhere, including clients that only accept static headers. Create a key in the console under API keys → New API key — it is shown once, so store it immediately.

{
  "mcpServers": {
    "surf": {
      "type": "http",
      "url": "https://mcp.asksurf.ai/mcp",
      "headers": {
        "Authorization": "Bearer sk-surf-your-key"
      }
    }
  }
}

In Claude Code:

claude mcp add --transport http --scope user surf https://mcp.asksurf.ai/mcp \
  --header "Authorization: Bearer sk-surf-your-key"

No credentials

Connecting with just the URL also works. Requests draw on a small daily allowance shared per IP address, which is enough to try things out. Add a key or sign in when you need your account's own credits and rate limits.

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

Local (stdio)

Runs the server on your own machine and talks to the data API directly.

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

Swap npx for bunx (and drop -y) for a faster start. Omitting SURF_API_KEY falls back to the anonymous allowance.

Config file locations

Tools

One tool per API domain. Each tool takes a command and optional params; the exact commands track the OpenAPI spec automatically, so new endpoints show up without an upgrade.

Usage examples

Once connected, your AI assistant uses the tools directly:

"What's the BTC price?"        → surf_market({ command: "price", params: { symbol: "BTC" } })
"Check this wallet"            → surf_wallet({ command: "detail", params: { address: "0xd8dA..." } })
"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 ..." } })
"AAPL fundamentals"            → surf_equity({ command: "overview", params: { symbol: "AAPL" } })

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 operations by API tag
3. Registers one MCP tool per tag, with command enums and parameter hints generated from the spec
4. Forwards each call to the data API, passing through your credentials

New API endpoints appear automatically when the spec updates — no upgrade needed.

Troubleshooting

Surf Skill vs MCP Server

Resources

• Console: agents.asksurf.ai — API keys, credits, usage
• npm: @surf-ai/surf-mcp
• GitHub: asksurf-ai/surf-mcp
• API Docs: docs.asksurf.ai