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

# Set up your agent

> Install the Kettio ranking pipeline into Claude Code, Codex, or any MCP client.

Install Kettio into a coding agent once, and it can rank your ad creative from local files for
the rest of the project. Two commands and a key.

<CardGroup cols={2}>
  <Card title="1. Get a key" icon="key" href="https://kettio.com/dashboard?section=api-keys">
    Dashboard → API Keys. Shown once — copy it now.
  </Card>

  <Card title="2. Install the server" icon="download" href="#install">
    One command per client. No npm publish required.
  </Card>
</CardGroup>

## Install

The server ships as a hosted tarball, so `npx` fetches it directly. Nothing to clone and nothing
to build.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add kettio \
      --transport stdio \
      -e KETTIO_API_URL=https://kettio.com \
      -e KETTIO_API_KEY=your-api-key-here \
      -- npx -y --package=https://kettio.com/downloads/kettio-mcp-server-3.0.0.tgz kettio-mcp
    ```

    Confirm it connected:

    ```bash theme={null}
    claude mcp list
    ```
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    codex mcp add kettio \
      --env KETTIO_API_URL=https://kettio.com \
      --env KETTIO_API_KEY=your-api-key-here \
      -- npx -y --package=https://kettio.com/downloads/kettio-mcp-server-3.0.0.tgz kettio-mcp
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add to `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS:

    ```json theme={null}
    {
      "mcpServers": {
        "kettio": {
          "command": "npx",
          "args": [
            "-y",
            "--package=https://kettio.com/downloads/kettio-mcp-server-3.0.0.tgz",
            "kettio-mcp"
          ],
          "env": {
            "KETTIO_API_URL": "https://kettio.com",
            "KETTIO_API_KEY": "your-api-key-here"
          }
        }
      }
    }
    ```

    Restart Claude Desktop after saving.
  </Tab>

  <Tab title="Other clients">
    Configure a stdio server with this command and two environment variables:

    ```bash theme={null}
    npx -y --package=https://kettio.com/downloads/kettio-mcp-server-3.0.0.tgz kettio-mcp
    ```

    ```bash theme={null}
    KETTIO_API_URL=https://kettio.com
    KETTIO_API_KEY=your-api-key-here
    ```
  </Tab>
</Tabs>

<Warning>
  Requires Node.js 18 or newer. Keep the key in the client's environment — never paste it into
  chat, commit it, or put it in browser code.
</Warning>

## Rank your first batch

Drop some creatives into the repo and ask in plain language:

> Rank the ads in `public/ads/` for women 30-45 considering a first premium skincare purchase who
> are skeptical of before/after claims. Goal is purchase intent, platform is Instagram.

The agent calls `rank_assets` with the local paths, and Kettio handles the upload. You get back
scores, confidence, a rationale per asset, and the close-pair panel outcome.

<Note>
  Point it at **files**, not URLs. `rank_assets` uploads local paths for you — the publish-to-a-URL
  step only applies when you call the [REST API](/guides/rank-api) directly.
</Note>

## Teach the agent the rules

The tool descriptions tell an agent *how* to call Kettio. They do not tell it how to
interpret the result, and the failure mode is predictable: agents report rank 1 as "the winner"
when it beat rank 2 by noise.

Save this as `AGENTS.md` (or `CLAUDE.md`) in the project:

```markdown AGENTS.md theme={null}
## Ranking ad creative with Kettio

Use the `rank_assets` MCP tool for any question about which creative will perform better.
Do not substitute your own numeric assessment of an image — you are not calibrated for it.

### Required inputs
- `assets`: local paths, 1-20 per call
- `audience`: describe the buying situation and the objection to overcome, not a demographic
  profile. "Women considering GLP-1 support who need credible purchase proof" is useful;
  "our target customers" is not.
- `copyContext`: include it whenever the ad copy is known. It enables copy-lift analysis.

### Reading the result
- Scores are relative WITHIN the batch. Never compare scores across batches, goals, or
  audiences.
- A gap smaller than 0.30 between two assets is not a ranking. Report them as tied, or
  escalate the pair rather than declaring a winner.
- Check `confidence` and the repetition spread before stating any result with certainty.
- If assets failed, the ordering is incomplete. Say so instead of reporting a winner.

### What NOT to claim
Kettio scores are a prioritization signal. They are not conversion probabilities and not
forecasts of CPA, ROAS, or lift. Never present a score as a predicted performance number.
```

<Tip>
  The 0.30 line is not arbitrary — it is the threshold at which Kettio itself treats two assets as
  a close pair and is willing to run a pairwise panel. See [Reading confidence](/concepts/confidence).
</Tip>

## Feed the agent the full docs

Every page here is available as Markdown for agent ingestion. Append `.md` to any URL:

```bash theme={null}
curl https://docs.kettio.com/guides/rank-api.md
```

There are also two aggregate files, generated automatically and always current:

| File                                                      | Contents                              |
| --------------------------------------------------------- | ------------------------------------- |
| [`/llms.txt`](https://docs.kettio.com/llms.txt)           | Index of every page with descriptions |
| [`/llms-full.txt`](https://docs.kettio.com/llms-full.txt) | Full text of the entire documentation |

Point an agent at `llms.txt` when it needs to look things up on demand, or paste
`llms-full.txt` when it needs the whole contract in context up front.

## Going beyond the MCP server

The MCP server is built for interactive and repo-local work. Switch to the REST API when you
need volume, scheduling, or a service that runs without a client attached.

<CardGroup cols={2}>
  <Card title="Rank API" icon="server" href="/guides/rank-api">
    `POST /api/v1/rank` — up to 20 assets per request, 60 evaluations per minute.
  </Card>

  <Card title="Agent loop" icon="arrows-rotate" href="/guides/agent-loop">
    The full generate → score → decide cycle with backoff and failure handling.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The agent doesn't see any Kettio tools" icon="plug-circle-xmark">
    Restart the client after saving the config. Then ask "what Kettio tools do you have?" — you
    should get `rank_assets`, `rank_ad_batch`, `get_rank_run`, and `list_audiences`. For Claude
    Code, `claude mcp list` shows connection status directly.
  </Accordion>

  <Accordion title="Paths aren't resolving" icon="folder-xmark">
    The server resolves relative paths against `KETTIO_WORKSPACE_PATH`, then
    `CLAUDE_PROJECT_DIR`, then the process working directory. If your agent runs from a different
    directory than the creatives, set `KETTIO_WORKSPACE_PATH` explicitly.
  </Accordion>

  <Accordion title="401 on every call" icon="key">
    The key is missing or invalid in the client environment. Keys are prefixed `agk_live_`.
    Generate a replacement from
    [Dashboard → API Keys](https://kettio.com/dashboard?section=api-keys) — the raw value is only
    shown at creation.
  </Accordion>

  <Accordion title="429 during a large batch" icon="gauge">
    The limit is 60 scoring evaluations per minute per key, and an asset with copy context can
    cost two. See [Limits and billing](/concepts/limits-and-billing).
  </Accordion>
</AccordionGroup>