Quickstart

Point Gecko at an API — even a messy, paywalled one with no published spec. It reads the API’s surface, turns every endpoint into a question-shaped, first-call-correct tool, and wires it into your agent. No client code, no key in a config file.

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).

Add any API to your agent

Comprehend and wire it in — one command

Straight from npx, no clone, no Python. It comprehends the API, seals your key in the OS keychain, and wires it into Claude Code over stdio.

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

It prompts once (hidden) for the key and injects it live at call time — the agent never sees it. Keyless APIs (e.g. Jupiter) skip the prompt.No openapi.json? That’s the normal case for a painful API — add takes whatever you have:

npx @geckovision/gecko add https://docs.someapi.com   # recovers a 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 it

Ask your agent — it calls it right

You:   search the API for X
Agent: ✓ called GET /v1/search?q=X  →  200, first try

No integration code, no docs-diving, no key in sight. That’s the whole loop.

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, then flip one flag (--mode live) for real data.

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

Gecko never holds your keys. A provider’s key is yours — sealed in your OS keychain, resolved only at call time. Control plane only: Gecko stores the API surface, never keys or response data. This whole path is local — it never touches Gecko’s servers.

Try it in 10 seconds — no install

Give your agent a live, Gecko-comprehended surface and watch it call correctly — 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" } } }

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

Serve over MCP

Prints the MCP URL + one-click add strings, then serves the API.

uvx --from "gecko-surf[serve]" gecko 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.

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

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

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 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.

Still V2 (designed, not built)

A vectorized semantic index (today’s catalog is lexical) and an auto-update job that re-comprehends an API when it ships a new version. See Stay correct.

Get Started

How it works

For AI agents

For API providers

Reference

Add any API to your agent

Try it in 10 seconds — no install

Other ways in

Claude Code plugin

Serve over MCP

Embed the SDK

No OpenAPI?

Good to know

How it works

For API providers

Prove it's correct

​Add any API to your agent

​Try it in 10 seconds — no install

​Other ways in

Claude Code plugin

Serve over MCP

Embed the SDK

No OpenAPI?

​Good to know

How it works

For API providers

Prove it's correct

Add any API to your agent

Try it in 10 seconds — no install

Other ways in

Good to know