Skip to main content
Gecko is a control plane, not a data plane. It holds the API’s surface, the generated tool defs, and correctness metadata — and never the data flowing through. That single invariant is what makes the rest of the design coherent.

​
The flow

Two auth relationships and two run modes, around one control-plane engine. Your agent connects to the MCP surface; the engine comprehends the API once, then serves and calls it — injecting credentials at call time and staying out of the data path.
Gecko flow — the agent states intent to the MCP surface; the control plane comprehends the API (ingest → catalog → tools) and the caller builds the request; access injects credentials at call time; in live mode the real API's data returns to the agent directly, never through Gecko; recorded mode synthesizes the response from the schema for $0 offline.

Your agent connects to the MCP surface; Gecko comprehends the API once, then injects credentials at call time and stays out of the data path.

Local gecko add stays zero-login; the identity plane gates only the hosted surface. In recorded mode the request is built and proven well-formed but the response is synthesized from the schema — it never touches the provider plane. In live mode access injects credentials and the agent gets the real API’s data directly; that data never passes through Gecko.

​
Invariants

Control plane, never data plane

Stores the API surface, tool defs, and correctness metadata only — never response payloads, user data, or secrets.

The engine is API-agnostic

Everything API-specific reduces to data (the spec) plus one adapter seam, Session.auth_headers(). Adding an API doesn’t touch ingest/catalog/tools/caller.

One code path, two modes

recorded and live differ only at the transport edge. The free offline simulation comes first; live smoke is the final check.

Auth is invisible to the agent

Tool defs never expose auth headers. The agent describes intent; Gecko injects credentials at call time.

​
Module map

The comprehension logic is the product and lives in the package; the MCP server, the client, and the scripts are thin transport.

​
The one seam that matters

Adding a new API should not require touching ingest, catalog, tools, or the caller. The only API-specific code is, at most, an auth adapter — an object that implements:
A public API uses the built-in no-auth adapter (returns {}); a paywalled API supplies a session that returns its tokens. See Access & auth.

​
Outcome logging (control-plane safe)

The validator and the evaluation harness append outcome metadata only — tool name, rank, ok/reason — to a JSONL log. They never write response payloads. Turning that metadata into a richer, multi-API correctness signal is V2 work and is not live today; see Status.

​
Security posture

  • Ingested spec/doc content is treated as untrusted input.
  • URLs are validated before fetching (no SSRF — private/loopback/link-local ranges and non-http schemes blocked).
  • Secrets come from the environment/session and are never logged or persisted; errors redact tokens before they’re raised.
  • Stdlib-first networking (urllib); minimal dependencies, so the engine ports anywhere.