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

# MCP installation

> Connect Claude Desktop, Codex, or any stdio MCP client to Kettio.

The Kettio MCP server gives an AI client tools for working with brand assets: finding local
files, reading brand context, generating and editing images, removing backgrounds, and opening
previews.

<Info>
  The server includes `rank_assets`, which scores local files directly — an MCP client does not
  need to touch the REST API to rank creative. See [Set up your agent](/quickstart/agent-setup)
  for the fastest path.
</Info>

## Requirements

* Node.js 18 or newer
* A Kettio API key from [Dashboard → API Keys](https://kettio.com/dashboard?section=api-keys)

## Connect your client

The server is distributed as a hosted tarball, so `npx` fetches it directly — there is 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
    ```

    Run `claude mcp list` and confirm `kettio` is connected.
  </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 your Claude Desktop config. On macOS that is
    `~/Library/Application Support/Claude/claude_desktop_config.json`:

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

## Verify the setup

Restart your MCP client after saving the configuration, then ask:

> What Kettio tools do you have?

You should see `rank_assets`, `rank_ad_batch`, `get_rank_run`, and `list_audiences`. Full schemas
are in the [tool reference](/mcp/tools).

<Warning>
  Kettio displays a new key only once. Do not commit it to your repository or paste it into public
  issue threads. If you lose it, create a replacement from
  [Dashboard → API Keys](https://kettio.com/dashboard?section=api-keys).
</Warning>

## How it fits together

```mermaid theme={null}
flowchart TD
    A[Agent<br/>Claude Code · Codex · Desktop] -->|"Rank the ads in public/ads/"| B[MCP server]
    B -->|reads local files| C[Your repo<br/>public/ads/]
    B -->|uploads + scores| D[Kettio API]
    D -->|scores · confidence · rationale| B
    B -->|ranked result| A
```

## Next

<CardGroup cols={2}>
  <Card title="Set up your agent" icon="robot" href="/quickstart/agent-setup">
    End-to-end install, plus the rules worth giving the agent.
  </Card>

  <Card title="Tool reference" icon="wrench" href="/mcp/tools">
    Every tool and its parameters.
  </Card>
</CardGroup>