surf — Claude Code MCP server: a call graph instead of guesswork
Maps an OpenAPI spec or a Solana IDL into a graph your agent checks a call against before sending it. Built for actions that cost money.
claude mcp add --transport http surf https://mcp.geckovision.tech/mcpWhat surf does
surf takes an API description and turns it into a graph. Each fact carries its origin: pulled from the surface, recovered from source code, or marked as unknown rather than invented. The agent walks that graph instead of making parameters up. Spending calls go through a simulation first and come back as a receipt — it lands, or it reverts with a classified error.
Provider keys sit in the OS keychain and are injected at call time. The model never sees a credential, and nothing lands in mcp.json. The server signs nothing, broadcasts nothing, and keeps no API responses — only surfaces and correctness metadata.
Hooking it into Claude takes one command, with two routes: the hosted endpoint https://mcp.geckovision.tech/mcp, or a local run via uvx gecko-surf, which needs uv on the machine. Auth is a separate step after that. Skip it and a paid call will bounce.
What it helps with
- get one exact API call instead of parameters the agent invented
- dry-run a paid Solana transaction before signing and read the receipt
- inject a provider key without exposing it to the model
- catch drift when a provider ships a change that breaks a working call
- see which facts the spec cannot supply, flagged in the graph
Example prompts for the agent
- What does the USDC peg look like at the moment?
- Put together a SOL to USDC swap plan on Meteora with bin_step 4
- Which fixtures start within the hour, and what odds do they carry now?
How to install surf
1Platform CLI: remote server
claude mcp add --transport http surf https://mcp.geckovision.tech/mcp2Platform CLI
claude mcp add surf -- uvx gecko-surfuvx runs the command named after the package; if the README names another one, use uvx --from gecko-surf <command>
1Platform CLI: remote server
codex mcp add surf --url https://mcp.geckovision.tech/mcp2Platform CLI
codex mcp add surf -- uvx gecko-surfuvx runs the command named after the package; if the README names another one, use uvx --from gecko-surf <command>
Config file
{
"mcpServers": {
"surf": {
"url": "https://mcp.geckovision.tech/mcp"
}
}
}{
"mcpServers": {
"surf": {
"command": "uvx",
"args": [
"gecko-surf"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from gecko-surf <command>
Config file
{
"servers": {
"surf": {
"type": "http",
"url": "https://mcp.geckovision.tech/mcp"
}
}
}{
"servers": {
"surf": {
"type": "stdio",
"command": "uvx",
"args": [
"gecko-surf"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from gecko-surf <command>
1Platform CLI: remote server
gemini mcp add -t http surf https://mcp.geckovision.tech/mcp2Platform CLI
gemini mcp add surf uvx gecko-surfuvx runs the command named after the package; if the README names another one, use uvx --from gecko-surf <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about surf
How do I install surf in Claude Code?
For the hosted server run claude mcp add --transport http surf https://mcp.geckovision.tech/mcp. For a local one use claude mcp add surf -- uvx gecko-surf, which requires uv.
What does surf do?
It builds a knowledge graph from an OpenAPI spec, docs site or Solana program IDL so your agent can verify a call before it counts. Spending actions are simulated and returned as a receipt.
Does the server hold my API keys?
Keys are stored in the OS keychain by gecko auth set <provider> and injected when a call is made. They never sit in your MCP client config.
