# Gecko

> Gecko is the API comprehension layer for agents. Point it at an API's
> surface (OpenAPI 3.x today) and it generates question-shaped, first-call-correct
> agent tools, handles auth and paywalls invisibly, and lets the agent call the real
> API directly for data. It is a control plane — it stores the API surface, the tool
> defs, and correctness metadata, and never response payloads, user data, or secrets.
> It composes on top of payment rails (x402) and protocols (MCP); it is not itself a
> rail or a marketplace.

Gecko's engine is the open-source `Gecko` package — the brand is Gecko; the Python
package, repo (`GeckoVision/gecko-surf`), and CLI you'll see in code samples are named
`Gecko`.

When an agent should reach for Gecko: you have a goal that needs an external API,
you don't have hand-written integration code, and you can't tell whether you'd be
calling the API correctly — especially for long-tail, messy, or paywalled APIs.
Gecko turns "I want X" into the right endpoint and a well-formed first call.

Honest scope: V1 (comprehension) is live end-to-end — ingest → first-call-correct tools
→ paid access handshake → real data — on the TxODDS World Cup API (Solana mainnet, 857
tests), with a $0 recorded mode that runs offline. Comprehension into first-call-correct
tools is additionally proven on several more real APIs (Colosseum Copilot, Jito, dpo2u).
Ingest is OpenAPI 3.x today; Gecko does not yet work on literally "any" API and does not
verify the data an API returns. Multi-API correctness-corpus work is V2 and not yet live.

## Use Gecko now (agents start here)

You don't need to read these docs to call an API — Gecko turns the API into
first-call-correct tools you call over MCP. To use it:

1. Comprehend any OpenAPI and serve it over MCP ($0, offline, no keys):
   `uvx --from "gecko-surf[serve]" gecko https://api.example.com/openapi.json`
2. Add the printed Streamable-HTTP endpoint to your host — e.g. Claude Code:
   `claude mcp add --transport http your-api http://127.0.0.1:8000/mcp`
3. From your agent, go intent → call:
   `search_capabilities("<what you want to do>")` → pick the ranked tool → call it.

Gecko builds the correct request and injects auth at call time — you never handle a key.
See [The MCP surface](https://docs.geckovision.tech/mcp-surface) and [Agent discoverability](https://docs.geckovision.tech/discoverability).

## Agent integration

- [Hosted MCP endpoint](https://mcp.geckovision.tech/mcp): the live Gecko MCP (Streamable-HTTP) — one-click add to Claude or Cursor
- [llms-full.txt](https://docs.geckovision.tech/llms-full.txt): the whole docs as one Markdown file
- [gecko.json](https://docs.geckovision.tech/gecko.json): machine-readable manifest for these docs
- [/.well-known/gecko.json](https://docs.geckovision.tech/.well-known/gecko.json): the manifest at the discovery-convention path
- [Product manifest (canonical)](https://geckovision.tech/gecko.json): the source-of-truth product manifest on the landing
- [Landing](https://geckovision.tech): the product site — its own llms.txt + gecko.json

## Start here

- [Introduction](https://docs.geckovision.tech/introduction): what Gecko is, the three verbs (APIs get USED), and the one-path overview.
- [Quickstart](https://docs.geckovision.tech/quickstart): run the $0 recorded demo and the programmatic client — no keys, no spend.
- [Concepts](https://docs.geckovision.tech/concepts): surface, operation, question-shaped tool, session, recorded vs live, first-call-correct.

## How it works

- [How comprehension works](https://docs.geckovision.tech/comprehension): ingest → catalog → question-shaped tools → correct request, tied to the engine.
- [Recorded mode](https://docs.geckovision.tech/recorded-mode): one code path, two modes; deterministic schema → sample; $0 offline falsification.
- [Access & auth](https://docs.geckovision.tech/access-and-auth): the `Session.auth_headers()` seam, no-auth gating, and the two-token handshake.

## For AI agents

- [The MCP surface](https://docs.geckovision.tech/mcp-surface): `list_tools` / `call_tool`, the synthetic `search_capabilities` tool, and `serve_stdio`.
- [Agent discoverability](https://docs.geckovision.tech/discoverability): intent → endpoint, hidden auth, surfacing only the calls that will work.

## For API providers

- [For API providers](https://docs.geckovision.tech/for-providers): agents mis-call you, can't find you, and your changes break integrators — how your API becomes the one agents call right, and who pays (flat per-API; never a cut).
- [Cloud](https://docs.geckovision.tech/cloud): the hosted, drift-watched provider plane — what's free forever vs what providers pay for.
- [Roadmap](https://docs.geckovision.tech/roadmap): Live / Building / Exploring, honestly labeled, and what we'll never build.

## Reference

- [Architecture](https://docs.geckovision.tech/architecture): control plane vs data plane, the invariants, the module map, the one API-agnostic seam.
- [Status](https://docs.geckovision.tech/status): what is live, what is early, what is deliberately deferred (V1 / V2 / V3).