Quickstart

Four commands. No install, no clone, no Python. Nothing here reaches a real API until you decide it should.

npx @geckovision/gecko doctor              # 1. check your environment
npx @geckovision/gecko add <spec-or-docs>  # 2. comprehend it — $0, no live call
npx @geckovision/gecko report <spec>       # 3. get the scorecard — grade + findings
npx @geckovision/gecko serve <spec>        # 4. your agent uses it over MCP

Or install once:

npm install -g @geckovision/gecko          # prebuilt binary — no Python needed
uv tool install "gecko-surf[serve]"        # or pip, if you want the Python package

gecko add <spec-or-docs>

npm install -g ships a prebuilt binary for macOS and Linux, so the CLI works with no Python toolchain at all. Install the PyPI package instead when you want to import gecko in your own code (from gecko import AgentApiClient).

Handing these docs to a coding agent? Point it at /llms.txt — a compact, agent-readable map of this site — or append .md to any page URL for raw markdown (e.g. /quickstart.md).

The four steps

doctor — read-only, no side effects

npx @geckovision/gecko doctor

Reports your setup and the exact next command. It changes nothing and calls nothing.

add — comprehend the surface, $0

npx @geckovision/gecko add https://api.provider.com/openapi.json

No openapi.json? Plenty of good APIs never publish one. add takes whatever you have:

npx @geckovision/gecko add https://docs.someapi.com   # recovers a draft spec from the docs
npx @geckovision/gecko add ./openapi.json             # a file you already have
npx @geckovision/gecko add api.stripe.com             # a bare domain — Gecko finds the spec

Everything ingested is treated as untrusted input: sanitized, quarantine-checked, SSRF-guarded. No live call to the API is made.

report — the scorecard

npx @geckovision/gecko report https://api.provider.com/openapi.json

A grade plus the specific, fixable findings — what an agent would get wrong on this surface, and why. This is the artifact to hand a provider.

serve — your agent uses it over MCP

npx @geckovision/gecko serve https://api.provider.com/openapi.json

Serves the comprehended surface over Streamable-HTTP MCP and prints one-click add strings. Defaults to recorded mode — nothing reaches the real API.

Plug it into your agent

# Claude Code
claude mcp add my-api -- npx -y @geckovision/gecko serve <spec> --stdio

// Cursor / VS Code / any MCP client — mcp.json
{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["-y", "@geckovision/gecko", "serve", "<spec>", "--stdio"]
    }
  }
}

Then your agent asks questions, not endpoints:

Which fixtures kick off in the next hour, and what are the current odds?
What is the peg state of USDC right now?
Plan a swap of SOL for USDC on Meteora, bin_step 4.

Going live is a separate, deliberate step

gecko auth set <provider>

The key goes to your OS keychain — never into mcp.json, never into a tool definition, never into the model’s context. Gecko resolves it at call time and sends it only to the API’s own host (out-of-band host anchoring). Keyless APIs skip this entirely.

Nothing in the first four commands calls a real API or spends anything. serve and the SDK default to recorded; live requires both a credential you set explicitly and an explicit --mode live.

Prove it offline first — $0 recorded mode

Every path has a recorded mode that runs the same code but synthesizes the response from the API’s own schema — no network, no key, no spend. Falsify the calls before going live.

uv run python -m gecko.demo    # goal → discover → correct call → data (recorded, $0)

The two modes differ only at the transport edge. See Recorded mode.

Try a live surface in 10 seconds

Give your agent a hosted, Gecko-comprehended surface — no pip, no spec, no key:

claude mcp add --transport http gecko-txline https://mcp.geckovision.tech/txline/mcp

That’s TxODDS TxLINE — 18 first-call-correct tools over a World Cup API with a two-token on-chain paywall a coding agent does not one-shot. Served recorded ($0/offline), so you explore the real surface without a subscription.

claude mcp add is Claude-Code-only. In Cursor, VS Code, or any MCP client, add the same endpoint to your mcp.json — transport is MCP Streamable HTTP (2025-11-25), not SSE:

{ "mcpServers": { "gecko-txline": { "type": "http", "url": "https://mcp.geckovision.tech/txline/mcp" } } }

On-chain, in one command

uvx --from "gecko-surf[serve,solana]" gecko-orquestra --program pumpfun --stdio

Gecko recovers the seeds the IDL drops, plans the full instruction, an external builder builds it, and a Receipt says whether it lands — before any signature.

gecko orquestra find-start "buy token X on pump"   # intent → the right start point

Other ways in

Claude Code plugin

Bundles the skills + a live demo surface.

/plugin marketplace add GeckoVision/gecko-surf
/plugin install gecko-surf@geckovision
/make-agent-ready https://api.example.com/openapi.json

Embed the SDK

For your own app or agent loop.

from gecko import AgentApiClient, public_session
client = AgentApiClient(spec, session=public_session())
hit = client.search("what you want")[0]
client.call(hit["name"], {...}, mode="recorded")

No OpenAPI?

Recover a draft spec from the docs, then comprehend it.

gecko from-docs https://api.example.com/docs

Review the draft (especially auth) before trusting it live.

Correctness in CI

First-call-correctness suites you can fail a build on.

gecko test <spec>

Good to know

Is it safe to run? (verify before you execute)

Nothing here pipes a remote script into a shell. Run in order and you never take an unchecked step:

Check (no side effects): npx @geckovision/gecko doctor — read-only; reports your setup and the exact next step.
Dry-run ($0): gecko serve <url> defaults to recorded — no request reaches the real API, nothing is billed.
Live: add --mode live (and gecko auth set <provider> first for a keyed API).

Gecko is open-source (Apache-2.0), installed from a public registry with a live SLSA provenance attestation tracing the package to its CI build — verifiable, not an opaque script. Control-plane only: it never stores your responses or your keys.

Spec served off-host? (e.g. Colosseum Copilot)

Gecko refuses to trust a spec’s servers[] host when the spec was fetched from a different origin (the token-exfil defense). Assert the real host yourself:

npx @geckovision/gecko add \
  https://raw.githubusercontent.com/GeckoVision/gecko-surf/main/gecko/examples/colosseum_copilot_openapi.json \
  --base-url https://copilot.colosseum.com/api/v1 --mode live

add prompts once for your PAT, seals it, pins the host, and connects in live mode. Drop --mode live to falsify the calls offline first.

Which platforms get the npx binary?

Linux (x64 + arm64) and Apple Silicon Macs — one command, no Python. On an Intel Mac or Windows, use the Python path (same CLI, your system’s own certificates):

uvx gecko-surf add api.stripe.com                    # no install, needs Python/uv
pip install gecko-surf && gecko add api.stripe.com   # or a normal pip install

Remote / hosted MCP?

Serve behind an HTTPS tunnel with --public-url https://<tunnel> (trusted for the Host/Origin guard). Gecko also runs a hosted surface at mcp.geckovision.tech.

Get Started

How it works

Use cases

On-chain

For AI agents

For API providers

Reference

The four steps

Plug it into your agent

Going live is a separate, deliberate step

Prove it offline first — $0 recorded mode

Try a live surface in 10 seconds

On-chain, in one command

Other ways in

Claude Code plugin

Embed the SDK

No OpenAPI?

Correctness in CI

Good to know

Architecture

The Receipt

Status

​The four steps

​Plug it into your agent

​Going live is a separate, deliberate step

​Prove it offline first — $0 recorded mode

​Try a live surface in 10 seconds

​On-chain, in one command

​Other ways in

Claude Code plugin

Embed the SDK

No OpenAPI?

Correctness in CI

​Good to know

Architecture

The Receipt

Status

The four steps

Plug it into your agent

Going live is a separate, deliberate step

Prove it offline first — $0 recorded mode

Try a live surface in 10 seconds

On-chain, in one command

Other ways in

Good to know