Skip to main content
Tools available once the MCP server is connected. Schemas here match @kettio/mcp-server v3.0.0.
Every ranking tool takes local file paths and handles the upload for you. Inside an MCP client there is no separate “publish to a URL” step — that only applies when you call the REST API directly.

​
Choosing a ranking tool

rank_assets

Scores and returns the ranking in one call. Use it for interactive work where you want the answer immediately.

rank_ad_batch

Queues the work and returns a run ID straight away. Use it for large batches, or when blocking the agent for the whole scoring pass is not acceptable.
Both reach the same scoring pipeline and bill identically. The difference is whether you wait.

​
rank_assets

Runs Kettio’s audience-fit model on 1–20 local ad creatives and returns the ranked winner, real Kettio scores, confidence, rationale, and close-pair panel outcome.

​
rank_ad_batch

Queues an asynchronous ranking run and returns a run ID immediately. Poll get_rank_run to collect the result. Takes the same parameters as rank_assets, plus: audience is required unless you supply audienceId.

​
get_rank_run

Polls one run created by rank_ad_batch.
Results are withheld until the whole batch finishes. A poll that returns queued or processing carries no ranking — it is not a partial answer to report from. Poll about every three seconds. Polling is never billed.

​
list_audiences

Lists saved audiences on the authenticated account, with their IDs. Pass an ID as audienceId to rank_ad_batch to score against a saved audience instead of retyping a description.
Creating, editing, and deleting audiences happens in the Kettio dashboard, not through this server. The MCP surface is read-only for audiences.

​
Workspace resolution

The server resolves relative paths against, in order:
  1. KETTIO_WORKSPACE_PATH when set
  2. CLAUDE_PROJECT_DIR when available (Claude Code)
  3. The MCP process working directory
Set KETTIO_WORKSPACE_PATH explicitly if your agent runs from a different directory than the repo holding the creatives.

Agent setup

Install the ranking pipeline into a coding agent end to end.

Agent loop

The generate → score → decide cycle, and when to drop to REST.