Skip to main content
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.

1. Get a key

Dashboard → API Keys. Shown once — copy it now.

2. Install the server

One command per client. No npm publish required.

​
Install

The server ships as a hosted tarball, so npx fetches it directly. Nothing to clone and nothing to build.
Confirm it connected:
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.

​
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.
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 directly.

​
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:
AGENTS.md
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.

​
Feed the agent the full docs

Every page here is available as Markdown for agent ingestion. Append .md to any URL:
There are also two aggregate files, generated automatically and always current: 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.

Rank API

POST /api/v1/rank — up to 20 assets per request, 60 evaluations per minute.

Agent loop

The full generate → score → decide cycle with backoff and failure handling.

​
Troubleshooting

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.
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.
The key is missing or invalid in the client environment. Keys are prefixed agk_live_. Generate a replacement from Dashboard → API Keys — the raw value is only shown at creation.
The limit is 60 scoring evaluations per minute per key, and an asset with copy context can cost two. See Limits and billing.