Server data from the Official MCP Registry
Point Gecko at an OpenAPI spec; get first-call-correct, auth-hidden agent tools.
Point Gecko at an OpenAPI spec; get first-call-correct, auth-hidden agent tools.
Remote endpoints: streamable-http: https://mcp.geckovision.tech/mcp
Valid MCP server (1 strong, 2 medium validity signals). No known CVEs in dependencies. Imported from the Official MCP Registry. 1 finding(s) downgraded by scanner intelligence.
Endpoint verified · Open access · 1 issue found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Set these up before or after installing:
Environment variable: X402_MODE
Available as Local & Remote
This plugin can run on your machine or connect to a hosted endpoint. during install.
From the project's GitHub README.
Gecko is the comprehension layer for the agentic economy. Point an agent at an API — even one behind human-shaped docs and a paywall — and it finds the right call, makes it correctly the first time, and runs. No client to write, no guessing whether the agent is calling it right.
Docs and endpoints are built for humans. Gecko translates them for agents.
Today a builder reads the docs, hand-writes a client, and still can't tell if the agent is calling the API correctly. Gecko removes that step: it ingests an API's surface (OpenAPI/docs), turns it into question-shaped, first-call-correct agent tools, drives the access/auth handshake, and lets the agent call the real API directly for data.
| Layer | What it does | Who |
|---|---|---|
| APIs get PAID | billing / settlement rail | Metera (gate402), MCPay |
| skills get DISTRIBUTED | marketplace / discovery | frames.ag, Bazaar |
| APIs get USED | comprehension / consumption | Gecko |
Gecko composes on top of x402 / MCP / pay.sh — it consumes a payment catalog as input. It is not a payment rail and not a marketplace. It is the layer that makes an API actually usable by an agent.
V1 is live on mainnet, end-to-end, against the real TxODDS World Cup API: ingest → comprehend → catalog → access (a two-token on-chain subscribe) → first-call-correct → real data. A $0 recorded mode runs the entire path offline with no subscription. 343 tests pass.
What is not proven: consumer willingness-to-pay — the actual decider for the business. That is discovery-interview work, not a demo claim. So: never read this repo as "Gecko is a proven business." What is real today is a working comprehension path on one genuinely painful API, and a clean, API-agnostic engine behind it.
Three acts, every number from a real run:
gecko test writes 32/32 first-call-correctness checks and emits them to CI.Gecko is a control plane, not a data plane. It holds the API's surface, the generated tool defs, and correctness metadata — it never stores response payloads, user data, or secrets. That invariant is what lets it ingest any API unilaterally.
flowchart TD
A["AI agent<br/>(has a goal, no API docs)"] -->|"what can this API do for X?"| S
subgraph SC["Gecko — comprehension layer (control plane)"]
direction TB
ING[("ingest<br/>OpenAPI / docs — the *surface* only")]
CAT["catalog<br/>intent → endpoint"]
TOOL["tools<br/>question-shaped, first-call-correct<br/>(auth hidden)"]
ACC["access<br/>subscribe / session handshake"]
ING --> CAT --> TOOL
TOOL --> ACC
end
S --> TOOL
ACC -->|"injects auth"| CALL
A -->|"calls the real API directly"| CALL["the real API<br/>(data plane — Gecko never stores it)"]
CALL -->|"data"| A
$ref
resolved, cycle/depth guarded). Never the response data.Session.auth_headers().| Surface | Entry point | Status |
|---|---|---|
| Serve any API to agents (paste a spec → hosted MCP + one-click "add to Claude/Cursor") | gecko serve <openapi-url> (or bare gecko <openapi-url>) | shipped |
| Generate + run first-call-correctness tests (before any live call) | gecko test <openapi-url> [-o test_api.py] | shipped |
| Recover a draft OpenAPI from human docs (no spec? point it at the doc page) | gecko from-docs <doc-url-or-path> [-o draft.json] | shipped |
Embed the SDK (search / list_tools / prepare / call) | from gecko import AgentApiClient | shipped |
| Forkable starter (an app on any API, ~20 lines, $0) | examples/_starter/ | shipped |
| $0 recorded demo (goal → discover → correct call → data, offline) | python -m gecko.demo | runnable now |
| Live demo against real TxODDS World Cup data | gecko.demo:live_demo (after subscribe) | mainnet-proven |
| Correctness harness (first-call-correct + flywheel log) | gecko.validator | shipped |
Point it at an OpenAPI and your agent can call it — no client code, auth handled, first call correct.
Serve it to your agent over MCP — prints the MCP URL + one-click "add to Claude / Cursor" strings:
# no install — run it straight from PyPI:
uvx --from "gecko-surf[serve]" gecko <openapi-url>
# or install the CLI (any system, no Python prereq):
curl -fsSL https://get.geckovision.tech/install.sh | bash
gecko <openapi-url>
It prints the comprehension summary, the MCP URL, and a one-click claude mcp add /
Cursor / VS Code string — then serves the API to your agent over Streamable-HTTP.
Or embed the SDK in your own app:
from gecko import AgentApiClient, public_session
client = AgentApiClient(spec, session=public_session())
hit = client.search("what you want")[0] # intent → right endpoint
client.call(hit["name"], {...}, mode="recorded") # correct call; "live" for real data
A complete forkable example: examples/_starter/ — an app on
any API in ~20 lines, runnable at $0. For a full agent (Telegram + an LLM tool-loop),
see examples/sos_vzla_bot/.
git clone https://github.com/GeckoVision/gecko-surf
cd gecko-surf && uv sync
uv run pytest # 343 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.
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.
| Path | Purpose |
|---|---|
gecko/ingest.py | OpenAPI 3.x → normalized Operation/Param ($ref resolution, guarded) |
gecko/catalog.py | Lexical capability search (intent → endpoint) |
gecko/tools.py | Operation → question-shaped agent tool defs (auth hidden) |
gecko/caller.py | tool + args → correct PreparedRequest (stdlib urllib) |
gecko/access.py | Session.auth_headers() — the engine/adapter seam; two-token session |
gecko/sample.py | deterministic schema → example (powers $0 recorded mode) |
gecko/client.py | AgentApiClient — search / list_tools / prepare / call |
gecko/mcp_server.py | McpSurface — the agent-facing MCP surface |
gecko/validator.py | replay + first-call-correct + JSONL outcome log (moat seed) |
gecko/demo.py | run() (recorded) + live_demo() |
gecko/serve.py | gecko <url> CLI — comprehend + serve over Streamable-HTTP MCP (+ one-click add) |
examples/_starter/ | forkable "app on any API" (engine-only, $0); examples/sos_vzla_bot/ is the full LLM agent |
scripts/subscribe.py | one-time on-chain subscribe (solders); simulate by default |
docs/ · private/ | strategy & PRD · gitignored business docs (canvas, pitch, numbers) |
Rule: the comprehension logic is the product and lives in gecko/. The MCP
server, the client, and scripts are thin transport.
| Layer | Tool |
|---|---|
| Language | Python 3.11+, managed with uv |
| Engine | stdlib-first (urllib); minimal deps; pyyaml for spec loading |
| Agent surface | mcp (Model Context Protocol) |
| Access / payments | x402; on-chain subscribe via solders; modes stub / live |
| Quality | ruff · mypy · pytest (343 tests) |
Source of truth: .env.example.
| Variable | Required | Default | Notes |
|---|---|---|---|
X402_MODE | no | stub | stub / live. Stub is intentional during user-testing — do not flip to live without founder go-ahead. |
TXODDS_* / session file | for live only | — | live World Cup access after the on-chain subscribe (see scripts/SUBSCRIBE.md) |
Recorded mode and the test suite need no keys.
uv run ruff format && uv run ruff check --fix
uv run mypy gecko
uv run pytest # targeted invocations preferred
uv run python -m gecko.demo # $0 recorded smoke
See CLAUDE.md for the architecture invariants, the subagent team, and
conventions.
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.
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Web content fetching and conversion for efficient LLM usage
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.