> ## 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

> doctor → add → report → serve. Map any API into a verified graph your agent traverses. $0, offline, no key. Going live is a separate, deliberate step.

Four commands. No install, no clone, no Python. Nothing here reaches a real API until
you decide it should.

```bash theme={null}
npx @geckovision/gecko doctor              # 1. check your environment
npx @geckovision/gecko add <spec-or-docs>  # 2. comprehend it, $0, no live call
npx @geckovision/gecko report <spec>       # 3. get the scorecard: grade + findings
npx @geckovision/gecko serve <spec>        # 4. your agent uses it over MCP
```

Or install once:

```bash theme={null}
npm install -g @geckovision/gecko          # prebuilt binary, no Python needed
uv tool install "gecko-surf[serve]"        # or pip, if you want the Python package

gecko add <spec-or-docs>
```

<Note>
  `npm install -g` ships a prebuilt binary for macOS and Linux, so the CLI works with no
  Python toolchain at all. Install the PyPI package instead when you want to import
  `gecko` in your own code (`from gecko import AgentApiClient`).
</Note>

<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 on this docs site for raw markdown (e.g.
  `/quickstart.md`).
</Note>

## No install at all: the hosted surface

The canonical setup lives on the landing site, not here:

* [`agents.md`](https://www.geckovision.tech/agents.md): the executable runbook an agent
  follows, from wiring to a verified first call.
* [`mcp-config.json`](https://www.geckovision.tech/mcp-config.json): every client's
  exact wiring (Claude Code, Claude web, Cursor, VS Code, any `mcp.json`).

For Claude Code, the flagship surface is one line:

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

That surface carries 16 tools: real Solana storefronts (`list_stores`), Orca Whirlpool
swaps (`plan_swap`), `find_start`, program graphs, and the money path
(`prepare_purchase` → your wallet signs → `verify_signed_transaction` →
`submit_transaction`). No account, no key. The host serves ten surfaces; they are listed
at [`/.well-known/gecko.json`](https://mcp.geckovision.tech/.well-known/gecko.json) and
described at [`catalog.md`](https://www.geckovision.tech/catalog.md).

Or let a skill do the wiring and verify the first call:

```bash theme={null}
npx skills add GeckoVision/gecko-surf
```

That installs seven skills: `gecko-setup`, `use-any-api`, `api-agent-ready`,
`x402-payai-setup`, `anti-poisoning`, `skill-guard`, `read-js-docs`.

## The four steps

<Steps>
  <Step title="doctor: read-only, no side effects">
    ```bash theme={null}
    npx @geckovision/gecko doctor
    ```

    Reports your setup and the exact next command. It changes nothing and calls nothing.
  </Step>

  <Step title="add: comprehend the surface, $0">
    ```bash theme={null}
    npx @geckovision/gecko add https://api.provider.com/openapi.json
    ```

    **No `openapi.json`?** Plenty of good APIs never publish one. `add` takes whatever
    you have:

    ```bash theme={null}
    npx @geckovision/gecko add https://docs.someapi.com   # recovers a draft 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 the spec
    ```

    Everything ingested is treated as **untrusted input**: sanitized, quarantine-checked,
    SSRF-guarded. No live call to the API is made.
  </Step>

  <Step title="report: the scorecard">
    ```bash theme={null}
    npx @geckovision/gecko report https://api.provider.com/openapi.json
    ```

    A grade plus the specific, fixable findings: what an agent would get wrong on this
    surface, and why. This is the artifact to hand a provider.
  </Step>

  <Step title="serve: your agent uses it over MCP">
    ```bash theme={null}
    npx @geckovision/gecko serve https://api.provider.com/openapi.json
    ```

    Serves the comprehended surface over Streamable-HTTP MCP and prints one-click add
    strings. Defaults to **recorded** mode: nothing reaches the real API.
  </Step>
</Steps>

## Plug it into your agent

```bash theme={null}
# Claude Code
claude mcp add my-api -- npx -y @geckovision/gecko serve <spec> --stdio
```

```jsonc theme={null}
// Cursor / VS Code / any MCP client: mcp.json
{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["-y", "@geckovision/gecko", "serve", "<spec>", "--stdio"]
    }
  }
}
```

Then your agent asks **questions**, not endpoints:

```
Which fixtures kick off in the next hour, and what are the current odds?
What is the peg state of USDC right now?
Plan a swap of SOL for USDC on Meteora, bin_step 4.
```

## Going live is a separate, deliberate step

```bash theme={null}
gecko auth set <provider>
```

The key goes to **your OS keychain**: never into `mcp.json`, never into a tool
definition, never into the model's context. Gecko resolves it at call time and sends it
only to the API's own host (out-of-band host anchoring). Keyless APIs skip this
entirely.

<Warning>
  Nothing in the first four commands calls a real API or spends anything. `serve` and the
  SDK default to **recorded**; live requires both a credential you set explicitly and an
  explicit `--mode live`.
</Warning>

## 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.

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

The two modes differ **only at the transport edge**. See [Recorded mode](/recorded-mode).

## Try a hosted HTTP surface in 10 seconds

Give your agent a hosted, Gecko-comprehended HTTP API: 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. For a live keyless
API, use `/pegana/mcp` the same way.

<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" } } }
  ```

  Every client's block for every surface is in
  [`mcp-config.json`](https://www.geckovision.tech/mcp-config.json).
</Note>

## On-chain, in one command

```bash theme={null}
uvx --from "gecko-surf[serve,solana]" gecko-orquestra --program pumpfun --stdio
```

Gecko recovers the seeds the IDL drops, plans the full instruction, an external builder
builds it, and a [Receipt](/receipt) says whether it lands, **before any signature**.

```bash theme={null}
gecko orquestra find-start "buy token X on pump"   # intent → the right start point
```

## 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="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}
    gecko from-docs https://api.example.com/docs
    ```

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

  <Card title="Correctness in CI" icon="circle-check">
    First-call-correctness suites you can fail a build on.

    ```bash theme={null}
    gecko test <spec>
    ```
  </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 <provider>` 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 host at `mcp.geckovision.tech`; the
    root `/mcp` serves `comprehend_api` and `list_surfaces`, and each surface lives at
    `/<name>/mcp`.
  </Accordion>
</AccordionGroup>

<CardGroup cols={3}>
  <Card title="Architecture" icon="diagram-project" href="/architecture" />

  <Card title="The Receipt" icon="receipt" href="/receipt" />

  <Card title="Status" icon="list-check" href="/status" />
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.