gecko-surf — project the Agent Surface for any API

An OpenAPI tells an agent what endpoints exist. MCP tells it how to invoke one. Neither tells it which calls, in what order, from what data — so the agent guesses, and on a painful API it guesses wrong.

Gecko derives the missing layer: the Agent Surface — the deterministic, provenance-carrying, safety-checked call graph your agent traverses to get the call right the first time. Point it at an API; it projects a surface built for agents, not a Swagger rewritten for them. Free and open source.

We don't hand you an OpenAPI. Unless you don't have one — then we generate one, and the surface above it.

Three layers — Gecko is the one nobody else fills

Shape and transport are probabilistic at the moment of use. The Surface is the deterministic answer, so the model doesn't have to guess. Gecko composes on OpenAPI (input) and MCP (transport) — it never replaces them.

Table of Contents

• Try it in 10 seconds

• Open source engine, hosted platform

• Watch it run

• What you'd actually type

• Architecture

• What you get

• The surface graph

• Make any API agent-usable

  • Registry surfaces

  • Alongside Context7

• Develop offline

• Going live

• What's in this repo

• Stack

• Environment variables

• Development

• FAQ

• Contributing

• Team

• License

Where Gecko sits — three verbs, three layers

We compose on x402 / MCP / pay.sh. We are not a payment rail or a marketplace.

Related MCP server: OpenAPI MCP Server

Try it in 10 seconds

One line, zero install. No pip, no spec, no key — 18 first-call-correct tools on the TxODDS TxLINE World Cup API (two-token on-chain paywall). Recorded demo ($0, schema-synthesized); use your own TxLINE session for live data. Also live: Jito at /jito/mcp, Jupiter at /jupiter/mcp.

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

Cursor / VS Code / any MCP client — same endpoint in mcp.json:

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

Transport is MCP Streamable HTTP (2025-11-25), not SSE — use streamablehttp_client, not sse_client. Ready for your own API? → Make any API agent-usable.

Prefer the CLI? gecko connect txline serves the same surface over stdio and adds an anonymous X-Gecko-Install-Id header (an opaque per-install id — no key, no PII; GECKO_TELEMETRY=off to skip) so distinct installs are countable. The copy-paste config above stays credential-free and header-free.

Open source engine, hosted platform

You just used both. The endpoint above is mcp.geckovision.tech — our hosted layer, running the exact engine in this repo.

This repository is the open-source engine: ingest, catalog, tool generation, the surface graph, the anti-poisoning sanitizer, and the auth seam. Apache-2.0, patent grant included, no feature gates. Clone it, embed the SDK, self-host the MCP server — that path is complete and stays free.

The hosted platform is where an API stays live for agents without you operating anything: comprehended surfaces served over Streamable-HTTP MCP, credentials injected at call time (never in mcp.json), per-surface key gating for paid and private APIs, and first-call-correctness suites that run against the surface as it drifts.

Who pays: API providers, to keep their surface live, correct, and agent-reachable — a flat price per API, never a cut of your calls. Developers never pay. Gecko takes no percentage, holds no funds, and settles nothing; when money moves it moves over x402 between the agent and the provider, and we are not in the path.

That split is the whole business model: the engine is open because distribution is the point, and the hosted layer is what a provider buys. → docs.geckovision.tech

Watch it run

The 70-second launch demo:

MP4 version

Every number from a real run:

• Plug in TxODDS → 18 first-call-correct tools, recorded/$0 first call (live when subscribed).

• Stay safe → poisoned-spec attacks that hit a naive agent 8/8 are blocked 0/8.

• Stay correct → gecko test writes 32/32 first-call-correctness checks for CI.

What you'd actually type

Gecko's surfaces take the question, not the endpoint. Once a surface is added, these are literal prompts:

Which fixtures kick off in the next hour, and what are the current odds?
Get me live odds updates for tomorrow's Brazil match
What's the price of this token and its 24h volume?
Show me Jito's current tip floor before I send this bundle

The second one is the interesting case. GET /api/odds/updates/{fixtureId} needs a fixtureId the agent doesn't have — so Gecko returns a chain, not a 404:

1. GET /api/fixtures/snapshot     # supplies fixtureId
2. GET /api/odds/updates/{fixtureId}

Onboarding your own API is the same shape — a sentence, not a config file:

/make-agent-ready https://api.example.com/openapi.json

gecko test https://api.example.com/openapi.json     # first-call-correctness suite
gecko from-docs https://docs.example.com/api        # no spec? recover a draft one

Architecture

Control plane, never data plane. Gecko holds the API surface, tool defs, and correctness metadata — never response payloads, user data, or secrets. That invariant is what lets it ingest any API unilaterally.

Interactive diagram · SVG

1. Ingest — OpenAPI 3.x → normalized ops/params (never response data).

2. Catalog — intent → endpoint (lexical at this scale).

3. Tools — question-shaped defs; auth headers hidden.

4. Access — subscribe/session via one seam: Session.auth_headers().

5. Call — agent hits the real API; Gecko injects credentials, stays off the data path.

6. Validate — replay, confirm first-call-correct, JSONL log → V2 correctness corpus seed.

What you get

The surface graph

Intent → the right chain of calls. Real questions rarely map to one endpoint. "Get live odds updates" needs a fixtureId — so Gecko plans a chain from the spec alone (no call logs, no training data):

agent intent: "get live odds updates"

plan:
  1. GET /api/fixtures/snapshot              # supplies fixtureId
  2. GET /api/odds/updates/{fixtureId}
explain:
  fixtureId ← FixtureId   [INFERRED · entity:fixture · high]

Spec-derived with provenance on every edge (EXTRACTED / INFERRED / DECLARED plus confidence). Plans are suggestions — your agent still makes every call. Measured offline: Stripe control cut false links 66,984 → 337 (−99.5%) while finding every known chain on a paywalled API — see docs/benchmarks.md. On by default in search_capabilities.

See it — graphviz for APIs. gecko graph svg <spec> renders the Surface: operations as nodes, feeds edges as arrows colored by provenance (emerald = DECLARED, amber = INFERRED). Deterministic, self-contained, structure-only (no payloads). This is a real render of the TxLINE surface:

from gecko import Surface
Surface.from_spec("https://api.example.com/openapi.json").render_svg()  # -> SVG string

Chains cross APIs too. Two surfaces never merge into one graph; they join only on a DECLARED entity the provider vouches for, so a name collision can't invent a link between unrelated APIs — design. What's next (body-carried join keys, semantic tiebreak, live validation) is in the correlation roadmap.

Make any API agent-usable

Point at an OpenAPI — no client code, auth handled, first call correct.

A · Claude Code — Marketplace plugin (skills + live demo surface):

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

Wires gecko-txline plus /make-agent-ready, /setup-x402, and anti-poisoning.

B · Everywhere else — CLI (Cursor, VS Code, any framework):

uvx --from "gecko-surf[serve]" gecko <openapi-url>

Prefer uvx (nothing to verify). Or prove the installer first with scripts/verify_install.py, then curl -fsSL https://get.geckovision.tech/install.sh | bash.

gecko <url> prints the MCP URL and one-click add links (Cursor / VS Code / raw). Claude Code → Marketplace; everything else → CLI. You don't need both.

Or embed the SDK — derive the Surface, then read it:

from gecko import Surface, public_session

surface = Surface.from_spec(spec, session=public_session())

surface.graph                       # the call graph: nodes + provenance-tagged edges
surface.plan("get live odds")       # the deterministic chain for an intent (+ explain)
surface.safety.clean                # anti-poisoning verdict (untrusted-spec defense)
surface.project("llms.txt")         # one artifact, N projections (gecko.json, SKILL.md, …)

Still want the call layer? Surface.client is the AgentApiClient — search / list_tools / prepare / call.

Forkable starter: examples/_starter/ (~20 lines, $0). Full agent: examples/sos_vzla_bot/.

Registry surfaces

gecko serve --registry colosseum --auth-env COLOSSEUM_COPILOT_PAT

Free surfaces need no account. Premium: GECKO_API_KEY via POST /registry/keys → OTP → gk_live_... (shown once; we store a salted hash). Your provider key stays local — Gecko never sees it.

Alongside Context7

Context7 tells the agent what to call; Gecko proves it's right before the call fires and chains the calls Context7-fed agents get wrong. Register both MCP servers side by side — the copy-pasteable mcp.json and the gecko verify-docs note are in docs/context7-integration.md. We compose Context7 as a docs input; we don't replace it.

Develop offline

$0, no keys, no subscription:

git clone https://github.com/GeckoVision/gecko-surf
cd gecko-surf && uv sync
uv run pytest                       # 1,630 passing
uv run python -m gecko.demo         # E2E: goal → discover → correct call → data (recorded, $0)

The recorded demo runs the same code path as live — it just synthesizes responses from the schema instead of hitting the network. That's the point: you can falsify the comprehension offline before spending a cent.

Going live

Real World Cup data. Recorded mode needs no subscription. For live data, do the one-time on-chain subscribe — see scripts/SUBSCRIBE.md — then pass a real Session:

from gecko.client import AgentApiClient
client = AgentApiClient(spec, base_url="https://...", session=my_session)
client.call(tool, args, mode="live")   # same path as recorded

Mainnet boundary: the subscribe transaction is founder-run only. The tooling simulates (no spend) and hands over the exact command; a human broadcasts.

What's in this repo

Rule: the comprehension logic is the product and lives in gecko/. The MCP server, the client, and scripts are thin transport.

Stack

Environment variables

Source of truth: .env.example.

Recorded mode and the test suite need no keys.

Development

uv run ruff format && uv run ruff check --fix
uv run mypy gecko
uv run pytest                       # 1,630 passing; targeted invocations preferred
uv run python -m gecko.demo         # $0 recorded smoke

See CLAUDE.md for the architecture invariants, the subagent team, and conventions.

FAQ

General

A wrapper is a snapshot: someone hand-writes tool defs from a spec, and they go stale on the next API change. Gecko is the generator, plus three things a wrapper doesn't have: the surface graph (a question that needs two calls gets a chain with provenance, not a 404), anti-poisoning (the spec is untrusted input, and a poisoned tool loses auth injection), and the auth seam (credentials are injected at call time, so the tool def never carries a key). Re-point at the spec and the tools regenerate; a wrapper needs a human.

The painful ones. A coding agent already one-shots Stripe — it has seen Stripe a million times. It does not one-shot a long-tail API with drifting docs, an odd auth handshake, or a paywall in front of the spec. That's the wedge. If your agent already calls your API correctly, you don't need Gecko.

No. Gecko hands the agent a correct, credentialed request; the agent calls the API directly. We are the control plane, never the data plane — see Architecture.

gecko from-docs <doc-url> recovers a draft spec from human documentation. It's a draft — review it, then feed it to gecko serve. If the docs are a JS-rendered SPA with no embedded schema, it will honestly recover nothing rather than hallucinate endpoints.

Install & use

No. The 10-second quickstart points your MCP client at a hosted surface. Installing (uvx --from "gecko-surf[serve]" gecko <url>) is only for comprehending your own API.

Streamable HTTP (2025-11-25). Use streamablehttp_client, not sse_client. This is the most common connection failure.

Yes, and nothing is held back. gecko serve <openapi-url> runs the same server this repo ships. The hosted layer saves you operating it; it doesn't unlock engine features.

gecko test <openapi-url> generates a first-call-correctness suite you can drop into CI, and the $0 recorded mode runs the identical code path offline. Falsify it before spending a cent.

Security & data

No. Gecko stores the API surface — operations, params, generated tool defs, and correctness metadata. Never response payloads, never user data, never secrets. It's an architectural invariant, not a policy: the data plane never touches our storage.

Not in mcp.json. Credentials resolve through one seam (Session.auth_headers()) and are injected at call time; the tool definitions the agent sees never contain them. For self-hosting, your provider key stays on your machine.

Ingested spec and doc text is treated as untrusted input. The sanitizer scans for prompt-injection and fund-routing patterns; a tool that trips it is quarantined per-tool — it loses auth injection and cannot be called with credentials, while the rest of the surface keeps working. Argument routing fails closed. The launch demo runs 8 attacks that land on a naive agent and are blocked 8/8.

No. Gecko holds no funds, signs nothing, and takes no cut. The on-chain subscribe tooling simulates by default and hands a human the exact command to broadcast.

Commercial

The engine is Apache-2.0 with a patent grant, no feature gates, and developers are never charged. Revenue comes from API providers paying a flat price to keep their surface hosted, correct, and agent-reachable. See Open source engine, hosted platform.

Never. Flat pricing per API, no take-rate, no funds custody. When payment happens it goes over x402 directly between the agent and the provider — we compose that rail, we are not it.

Your API becomes reachable by agents that would otherwise call it wrong or not at all: a hosted MCP surface, first-call-correctness suites that track your spec as it drifts, key gating for paid or private endpoints, and the anti-poisoning layer in front of it. Your own MCP server, if you have one, stays intact — we aggregate, we don't replace. → docs.geckovision.tech

Contributing

The engine is open because distribution is the point. See CONTRIBUTING.md for setup, the mandatory gate (ruff · mypy · pytest · $0 demo), and the architectural ground rules — the control-plane invariant, auth-injection, untrusted-spec handling, and no-SSRF are enforced in review, not just style.

Skills welcome. skills/ is the gecko-surf Claude Code plugin marketplace (use-any-api, read-js-docs, anti-poisoning, api-agent-ready, x402-payai-setup). Adding one is a SKILL.md plus a line in the plugin manifest — the contributing guide has the details, including the rule that a skill points at engine code rather than restating it.

Team

• Ernani (@ernanibritto) — Technical co-founder. Builds the Gecko engine end-to-end: ingest, comprehension, the access layer, and the MCP surface.

• Leticia (@0xLeti) — Co-founder, Product Designer. 8+ years designing for enterprises and startups; ex-Liga Ventures.

License

Apache License 2.0 — see LICENSE and NOTICE. Apache-2.0 carries an explicit patent grant. The engine is open (the distribution funnel); the correctness corpus and hosted layer stay private (open-core).

The comprehension layer for the agentic economy.