# surf

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 22
- Author: GeckoVision
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/GeckoVision/gecko-surf
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/mcp/surf

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Remote server: `https://mcp.geckovision.tech/mcp`

## Install

### Claude Code (native platform)

1. **Platform CLI: remote server**
```bash
claude mcp add --transport http surf https://mcp.geckovision.tech/mcp
```

2. **Platform CLI**
```bash
claude mcp add surf -- uvx gecko-surf
```
uvx runs the command named after the package; if the README names another one, use uvx --from gecko-surf <command>

### Codex

1. **Platform CLI: remote server**
```bash
codex mcp add surf --url https://mcp.geckovision.tech/mcp
```

2. **Platform CLI**
```bash
codex mcp add surf -- uvx gecko-surf
```
uvx runs the command named after the package; if the README names another one, use uvx --from gecko-surf <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "surf": {
            "url": "https://mcp.geckovision.tech/mcp"
        }
    }
}
```
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "surf": {
            "type": "http",
            "url": "https://mcp.geckovision.tech/mcp"
        }
    }
}
```
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

1. **Platform CLI: remote server**
```bash
gemini mcp add -t http surf https://mcp.geckovision.tech/mcp
```

2. **Platform CLI**
```bash
gemini mcp add surf uvx gecko-surf
```
uvx runs the command named after the package; if the README names another one, use uvx --from gecko-surf <command>

## When to use it
- 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
- 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?

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md