> ## Documentation Index
> Fetch the complete documentation index at: https://docs.geckovision.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Point Gecko at any API and your agent calls it right the first time. One command to add it, $0 recorded mode to prove every call offline first.

Point Gecko at an API — even a messy, paywalled one with no published spec. It reads the
API's *surface*, turns every endpoint into a question-shaped, first-call-correct tool, and
wires it into your agent. No client code, no key in a config file.

<Note>
  **Handing these docs to a coding agent?** Point it at
  [`/llms.txt`](https://docs.geckovision.tech/llms.txt) — a compact, agent-readable map of
  this site — or append `.md` to any page URL for raw markdown (e.g. `/quickstart.md`).
</Note>

## Add any API to your agent

<Steps>
  <Step title="Comprehend and wire it in — one command">
    Straight from `npx`, no clone, no Python. It comprehends the API, seals your key in
    the OS keychain, and wires it into Claude Code over stdio.

    ```bash theme={null}
    npx @geckovision/gecko add https://api.provider.com/openapi.json
    ```

    It prompts once (hidden) for the key and injects it **live** at call time — the agent
    never sees it. Keyless APIs (e.g. Jupiter) skip the prompt.

    **No `openapi.json`?** That's the normal case for a painful API — `add` takes whatever
    you have:

    ```bash theme={null}
    npx @geckovision/gecko add https://docs.someapi.com   # recovers a spec from the docs
    npx @geckovision/gecko add ./openapi.json             # a file you already have
    npx @geckovision/gecko add api.stripe.com             # a bare domain — Gecko finds it
    ```
  </Step>

  <Step title="Ask your agent — it calls it right">
    ```
    You:   search the API for X
    Agent: ✓ called GET /v1/search?q=X  →  200, first try
    ```

    No integration code, no docs-diving, no key in sight. That's the whole loop.
  </Step>

  <Step title="Prove it offline first — $0 recorded mode">
    Every path has a **recorded mode** that runs the *same code* but synthesizes the
    response from the API's own schema — no network, no key, no spend. Falsify the calls
    before going live, then flip one flag (`--mode live`) for real data.

    ```bash theme={null}
    uv run python -m gecko.demo    # goal → discover → correct call → data (recorded, $0)
    ```
  </Step>
</Steps>

<Note>
  **Gecko never holds your keys.** A provider's key is yours — sealed in *your* OS keychain,
  resolved only at call time. Control plane only: Gecko stores the API surface, never keys or
  response data. This whole path is **local** — it never touches Gecko's servers.
</Note>

## Try it in 10 seconds — no install

Give your agent a live, Gecko-comprehended surface and watch it call correctly — no `pip`,
no spec, no key:

```bash theme={null}
claude mcp add --transport http gecko-txline https://mcp.geckovision.tech/txline/mcp
```

That's **TxODDS TxLINE** — 18 first-call-correct tools over a World Cup API with a two-token
on-chain paywall a coding agent does *not* one-shot. Served **recorded** (\$0/offline), so you
explore the real surface without a subscription.

<Note>
  `claude mcp add` is Claude-Code-only. In **Cursor**, **VS Code**, or any MCP client, add the
  same endpoint to your `mcp.json` — transport is **MCP Streamable HTTP** (`2025-11-25`), not SSE:

  ```jsonc theme={null}
  { "mcpServers": { "gecko-txline": { "type": "http", "url": "https://mcp.geckovision.tech/txline/mcp" } } }
  ```
</Note>

## Other ways in

<CardGroup cols={2}>
  <Card title="Claude Code plugin" icon="puzzle-piece">
    Bundles the skills + a live demo surface.

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

  <Card title="Serve over MCP" icon="server">
    Prints the MCP URL + one-click add strings, then serves the API.

    ```bash theme={null}
    uvx --from "gecko-surf[serve]" gecko https://api.example.com/openapi.json
    ```
  </Card>

  <Card title="Embed the SDK" icon="code">
    For your own app or agent loop.

    ```python theme={null}
    from gecko import AgentApiClient, public_session
    client = AgentApiClient(spec, session=public_session())
    hit = client.search("what you want")[0]
    client.call(hit["name"], {...}, mode="recorded")
    ```
  </Card>

  <Card title="No OpenAPI?" icon="file-magnifying-glass">
    Recover a draft spec from the docs, then comprehend it.

    ```bash theme={null}
    uv run gecko from-docs https://api.example.com/docs
    ```

    Review the draft (especially auth) before trusting it live.
  </Card>
</CardGroup>

## Good to know

<AccordionGroup>
  <Accordion title="Is it safe to run? (verify before you execute)">
    Nothing here pipes a remote script into a shell. Run in order and you never take an
    unchecked step:

    1. **Check (no side effects):** `npx @geckovision/gecko doctor` — read-only; reports your
       setup and the exact next step.
    2. **Dry-run (\$0):** `gecko serve <url>` defaults to **recorded** — no request reaches the
       real API, nothing is billed.
    3. **Live:** add `--mode live` (and `gecko auth set` first for a keyed API).

    Gecko is open-source (Apache-2.0), installed from a public registry **with a live SLSA
    provenance attestation** tracing the package to its CI build — verifiable, not an opaque
    script. Control-plane only: it never stores your responses or your keys.
  </Accordion>

  <Accordion title="Spec served off-host? (e.g. Colosseum Copilot)">
    Gecko refuses to trust a spec's `servers[]` host when the spec was fetched from a
    different origin (the token-exfil defense). Assert the real host yourself:

    ```bash theme={null}
    npx @geckovision/gecko add \
      https://raw.githubusercontent.com/GeckoVision/gecko-surf/main/gecko/examples/colosseum_copilot_openapi.json \
      --base-url https://copilot.colosseum.com/api/v1 --mode live
    ```

    `add` prompts once for your PAT, seals it, pins the host, and connects in live mode. Drop
    `--mode live` to falsify the calls offline first.
  </Accordion>

  <Accordion title="Which platforms get the npx binary?">
    Linux (x64 + arm64) and Apple Silicon Macs — one command, no Python. On an Intel Mac or
    Windows, use the Python path (same CLI, your system's own certificates):

    ```bash theme={null}
    uvx gecko-surf add api.stripe.com                    # no install, needs Python/uv
    pip install gecko-surf && gecko add api.stripe.com   # or a normal pip install
    ```
  </Accordion>

  <Accordion title="Remote / hosted MCP?">
    Serve behind an HTTPS tunnel with `--public-url https://<tunnel>` (trusted for the
    Host/Origin guard). Gecko also runs a hosted surface at `mcp.geckovision.tech`.
  </Accordion>

  <Accordion title="Still V2 (designed, not built)">
    A vectorized semantic index (today's catalog is lexical) and an auto-update job that
    re-comprehends an API when it ships a new version. See [Stay correct](/stay-correct).
  </Accordion>
</AccordionGroup>

<CardGroup cols={3}>
  <Card title="How it works" icon="gears" href="/comprehension" />

  <Card title="For API providers" icon="building" href="/for-providers" />

  <Card title="Prove it's correct" icon="circle-check" href="/recorded-mode" />
</CardGroup>