Developer

Model Context Protocol Server

Integrate Kettio directly into your AI workflows. Use the MCP server to generate, edit, inspect, and manage brand assets; use the REST Rank API when agents need high-volume scoring and simulation runs.

How It Works

┌─────────────────┐
│   Developer     │
│  (Claude/CLI)   │
└────────┬────────┘
         │ "Generate hero image"
         ▼
┌─────────────────┐
│   MCP Server    │
│  (This package) │
└────────┬────────┘
         │ 1. Analyze local assets
         │ 2. Call Kettio API
         ▼
┌─────────────────┐
│   Kettio API    │
│  (Your backend) │
└────────┬────────┘
         │ 3. Generate with AI models
         │ 4. Return signed URLs
         ▼
┌─────────────────┐
│   MCP Server    │
│  Downloads      │
└────────┬────────┘
         │ 5. Save to repo
         ▼
┌─────────────────┐
│  Your Repo      │
│  public/images/ │
└─────────────────┘

Rank API Handoff

The MCP server is the asset workflow layer. It can find local files, analyze brand context, generate images, edit images, remove backgrounds, and open previews. The rank endpoint is a REST API: call POST /api/v1/rank when your agent needs to score batches, compare uploaded assets, measure copy lift, or run thousands of simulations per month.

┌────────────────────────┐
│ MCP asset workflow     │
│ list/generate/edit     │
└───────────┬────────────┘
            │ stable https URLs or data:image payloads
            ▼
┌────────────────────────┐
│ REST Rank API          │
│ POST /api/v1/rank      │
└───────────┬────────────┘
            │ ranked[], copy_lift, panel_outcome
            ▼
┌────────────────────────┐
│ Agent decision loop    │
│ edit, launch, reject   │
└────────────────────────┘

Batch scoring pattern

For batch uploads, have the agent collect or generate assets through MCP, upload them to durable https:// URLs, then call the Rank API with copy_context, platform, and refine_close_pairs. The MCP tool list below does not currently expose a separate rank tool.

Start here

Connect Your Client

Open API Keys in your dashboard, create a key, choose your client in the setup modal, and copy the configuration with your key already inserted. Node.js 18 or newer is required.

Codex

Run the command supplied after key creation. Codex stores the server configuration for future sessions.

codex mcp add kettio \
  --env KETTIO_API_URL=https://kettio.com \
  --env KETTIO_API_KEY=your-api-key-here \
  -- npx -y @kettio/mcp-server

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "kettio": {
      "command": "npx",
      "args": ["-y", "@kettio/mcp-server"],
      "env": {
        "KETTIO_API_URL": "https://kettio.com",
        "KETTIO_API_KEY": "your-api-key-here"
      }
    }
  }
}

Other MCP Clients

Configure a stdio server with npx -y @kettio/mcp-server and provide the two environment variables below.

KETTIO_API_URL=https://kettio.com
KETTIO_API_KEY=your-api-key-here

Verify Setup

Restart your MCP client after saving the configuration, then ask: “What Kettio tools do you have?” You should see the asset tools listed below.

Keep your key private

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.

Available Tools

list_assets

Lists all image assets in your repository. Automatically finds common asset directories like public/images.

analyze_brand

Scans your repo for brand guideline docs and color tokens. Returns a summary of candidate files and extracted colors that the AI can use as brand context.

generate_assets

Generate new brand assets based on a text prompt. Supports brand context injection.

Parameters

prompt (string): Description of the image
count (number): Number of images (default: 3)
outputPath (string): Where to save (auto-detects if empty)
format (string): 'png', 'svg', 'webp'
brandContext (string): Additional brand guidelines
referenceAssets (string[]): Paths to style reference images

edit_assets

Edit existing assets using AI instructions. Perfect for refining generated images.

Parameters

assetPaths (string[]): Paths to assets to edit
prompt (string): Edit instructions
model (string): 'nano-banana' | 'nano-banana-pro' | 'chatgpt-image-1.5' | 'chatgpt-image-1-mini'

remove_bg_and_vectorize

Remove background and convert to SVG. Ideal for logos and icons.

Parameters

assetPath (string): Path to image
outputPath (string): Optional save path

open_assets

Open image files in your system's default viewer for quick preview.