Gecko: turn any API into first-call-correct agent tools without exposing keys

Your coding agent can already talk to APIs. That is not the hard part. The hard part is three failure modes that show up the moment you leave the happy-path tutorial:

• The agent guesses the request shape and burns a chain of 400 / 401 responses.
• Someone pastes a live key into mcp.json, an env file, or the prompt — and that secret is now model-visible.
• A skill, docs page, or image has been quietly edited to steer the agent into a dangerous call.

Gecko (site: geckovision.tech, open-source engine: GeckoVision/gecko-surf) is aimed squarely at those three problems. Point it at an API surface — an OpenAPI document, a docs site it can recover a spec from, or a bare domain — and it turns that surface into question-shaped, first-call-correct tools your agent picks by intent. Keys stay on your machine. The call path is screened. And you can prove the whole loop offline for $0 before you spend rate limit or real money.

Click to zoom

The product is Solana-native in composition (x402 settlement demos, Surfpool in the story, Superteam Brasil / Dev3Pack backing) without pretending to be a chain. Builder: Ernani Britto (@us3Gecko).

Where Gecko sits (three verbs)

The docs draw a clean line that most agent decks blur. Three jobs in the agentic economy:

Gecko is not a payment rail and not a marketplace. It composes on top of x402 and MCP. That framing matters for DevRel: when you teach agents on Solana you already have pieces for pay (x402) and for program surfaces (Orquestra). Gecko is the missing middle for arbitrary HTTP APIs — Stripe, Twilio, Jupiter, paywalled sports data, whatever is next.

The three promises

1. Right the first time. Gecko reads the API before the agent calls it: right endpoint, params, and auth shape. Marketing claim backed by published first-call-correct numbers on large specs (e.g. Stripe-scale operation sets, Twilio, Jupiter — see their site/docs for the latest figures).
2. Keys stay hidden. Provider keys seal into the local OS keychain. They are injected only at the moment of the call, and only to the API's own host. Not in prompts, not in plaintext config, not inside the model context.
3. Poison gets caught. Docs, skills, and images can be mutated to trick an agent. Gecko screens the surface on the way in so a tool with changed actions does not push a dangerous move.

Control-plane only: Gecko stores the API surface, tool definitions, and correctness metadata. It does not store response payloads, user data, or secrets. The agent calls the real API for data; Gecko stays out of that data path after injection.

Try it: one command

Brand is Gecko. Package is gecko-surf on PyPI. CLI / npx entry is gecko / @geckovision/gecko.

# Comprehend + wire into the agent (stdio / local)
npx @geckovision/gecko add https://api.provider.com/openapi.json

# No openapi.json? Normal case for painful APIs:
npx @geckovision/gecko add https://docs.someapi.com   # recover spec from docs
npx @geckovision/gecko add ./openapi.json             # local file
npx @geckovision/gecko add api.stripe.com             # bare domain

# Python / offline serve path (from docs)
uvx --from "gecko-surf[serve]" gecko https://api.example.com/openapi.json
# then: claude mcp add --transport http your-api http://127.0.0.1:8000/mcp

Keyless public APIs (Jupiter is the example they use) skip the key prompt. For keyed APIs the prompt is one-shot and hidden; injection is live at call time.

Hosted MCP: see a hard API work

Without installing anything you can attach a live, Gecko-comprehended surface. Docs currently push the TxODDS TxLINE World Cup API demo — a multi-tool, paywalled surface that coding agents do not one-shot cleanly — over Streamable HTTP MCP:

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

Cursor / VS Code style mcp.json (Streamable HTTP, not legacy SSE):

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

That demo is served in recorded mode by default: same code path, synthesized responses from schema, $0 / offline, so you explore the real surface without a subscription. Flip to live when you have access. The live path is the one they run on Solana mainnet with an on-chain paywall handshake — which is why this shows up in a Solana DevRel feed, not only a generic agents newsletter.

Recorded mode ($0)

Every path has a recorded mode that runs the same code but does not hit the network. Deterministic schema → sample response. Use it to falsify tool selection and argument shape before you burn rate limits or mainnet fees. Then one flag to live. This is the teaching tool I want in every agent workshop: prove the call offline, then flip.

How comprehension works (builder mental model)

1  Ingest   OpenAPI 3.x  OR  recover surface from docs page
2  Catalog  capability list (lexical)  intent → endpoint
3  Comprehend  each operation → question-shaped tool
               (auth headers hidden from the agent)
4  Access   Session.auth_headers() seam / subscription handshake
5  Call     agent hits the REAL API; Gecko injects creds and exits

On the MCP side the agent loop is intentionally boring: search_capabilities("what I want") → pick the ranked tool → call_tool. You are not dumping every endpoint into the context window and hoping.

For API providers

Provider pitch is the other half of the product: agents already hit your docs traffic (they cite industry stats on agent share of docs hits). Mis-calls and brittle integrations are your support load. Gecko's provider plane wants your API to be the one agents call correctly, with optional x402 so correct calls can settle, and a flat monthly fee per API rather than a take-rate on volume. Worth reading For API providers and Cloud if you run a Solana or crypto API and care about agent distribution.

Honest scope

• Live now (V1 comprehension): ingest → tools → access handshake → real data, with recorded mode and published demo surfaces. Open source engine on GitHub under Apache-2.0.
• Not Gecko's job: verifying that the data an API returns is true; being a wallet; being a skill store; replacing your product's own auth product.
• Early project: stars and surface area will move fast. Treat version numbers, MCP URLs, and benchmark claims as living — check docs the day you integrate.
• Naming: product Gecko, repo/package historically gecko-surf. Do not confuse with CoinGecko.

How this pairs with other Solana agent tooling

• Orquestra — Solana program IDL → REST + MCP. Gecko — arbitrary HTTP API → MCP tools.
• x402 — pay for the call. Gecko — form the call correctly and keep the key offline.
• Solana AI agents 2026 — ecosystem map; Gecko is a concrete install path for the "agent needs an external API" chapter.

Resources

• Product: geckovision.tech
• Docs: docs.geckovision.tech · agent index llms.txt
• GitHub: GeckoVision/gecko-surf
• PyPI: gecko-surf
• Hosted MCP (TxLINE demo): https://mcp.geckovision.tech/txline/mcp
• Install script: get.geckovision.tech
• X: @us3Gecko · builder @ernanibritto
• Discord: community

Bottom line

If your workshop still ends with "paste the key into mcp.json and hope the model reads the OpenAPI," you are teaching the failure mode. Gecko is the cleaner story for 2026 agent builders: comprehend the surface, hide the key, prove offline, then call live — including paywalled Solana-settled APIs when you need them.