@komplit/mcp-server

MCP (Model Context Protocol) server for the Komplit Creative Platform — AI agents use this as their sole interface for creative operations. Published to npm.

Quick Install

npm install -g @komplit/mcp-server

The package exposes a komplit-mcp binary using stdio transport — works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

Claude Desktop Setup

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "komplit": {
      "command": "npx",
      "args": ["-y", "@komplit/mcp-server@latest"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "komplit": {
      "command": "komplit-mcp"
    }
  }
}

Environment Variables

| Variable | Required | Default | Description | | ----------------- | -------- | ------------------------------------------------- | -------------------- | | KOMPLIT_API_URL | No | https://komplit-dev-api-fgvrsq73mq-as.a.run.app | Komplit API base URL |

Authentication

The MCP server uses device-flow OAuth 2.0 — no API key needed in config. On first tool call:

1. The server returns an activation URL
2. Open the URL in a browser, log in with your Komplit account
3. Call auth_wait_for_login to confirm
4. Credentials are cached at ~/.komplit/credentials.json
5. Subsequent calls auto-refresh via refresh token

To clear credentials and re-authenticate: delete ~/.komplit/credentials.json.

Architecture

AI Agent → MCP Tool Call → komplit-mcp (stdio) → HTTP → Komplit API → DB / TigerBeetle / Vendors

The MCP server contains zero business logic — every tool is a thin proxy that forwards requests over HTTP to the Komplit API. Authentication (device flow, refresh, 401-retry) is handled transparently.

Transports:

• server-stdio.ts → StdioServerTransport (default, npm binary)
• server-http.ts → StreamableHTTPServerTransport (for remote/hosted deployments)

Tools (39)

Brief & Ideation

| Tool | Description | |------|-------------| | brief_create | Create or continue a creative brief via interview or oneshot mode | | concepts_generate | Generate content concepts from a completed brief |

Asset Production

| Tool | Description | |------|-------------| | assets_produce | Produce creative assets (image, carousel, video) | | assets_status | Poll asset production job status | | audio_treatment_apply | Apply audio treatment (music/narration/both) to video | | audio_treatment_status | Poll audio treatment job status |

Creative QA

| Tool | Description | |------|-------------| | creative_qa_score | Score creative asset via Neurons/Kantar | | creative_qa_status | Poll QA scoring job status |

Branded Assets

| Tool | Description | |------|-------------| | brand_assets_compose | Compose branded assets from template + production assets | | brand_assets_status | Poll branded asset composition job status | | brand_assets_upload | Create an upload handoff link (brand assets / product references) via resource_link | | brand_assets_upload_status | Poll an upload handoff until the user completes it (returns product refs / brand profile ids) | | brand_templates_browse | List master templates with previewUrl | | brand_templates_submit | Submit master template + brand profile for approval | | brand_templates_status | Poll template submission/approval job status | | brand_profiles_list | List active brand profiles for the tenant | | brand_profiles_get | Get a single brand profile with props | | brand_toolkits_list | List brand toolkits (logos, colors, fonts) | | brand_toolkits_create | Create a new brand toolkit |

Publishing & Connections

| Tool | Description | |------|-------------| | connections_ensure | Initiate OAuth (Instagram / X) — returns consent URL if needed | | connections_list | List active platform connections | | connections_set_autopublish | Toggle autopublish (skip human approval) | | connections_revoke | Disconnect a platform — DESTRUCTIVE | | posts_publish | Publish post to a platform (returns approval URL via resource_link) | | posts_boost | Boost post with paid promotion — SPEND | | posts_status | Poll publish/boost job status |

Snapshots

| Tool | Description | |------|-------------| | snapshots_save | Save agent state as versioned snapshot | | snapshots_restore | Restore agent state from snapshot | | snapshots_list | List all snapshots | | snapshots_delete | Delete snapshot(s) — DESTRUCTIVE |

Billing & Auth

| Tool | Description | |------|-------------| | billing_balance | Get current credit balance | | billing_checkout_link | Create Stripe checkout session for credit purchase (returns URL via resource_link) | | billing_wait_for_credit | Poll until credit purchase completes | | auth_wait_for_login | Wait for device-flow auth (blocks up to 120s) |

Skills

| Tool | Description | |------|-------------| | skills_list | List all skills for the tenant | | skills_get | Get fully-resolved brand+campaign skill bodies | | skills_upsert | Upsert tenant instance params for a skill | | skills_check_escalations | Check which escalation thresholds are triggered |

Discovery

| Tool | Description | |------|-------------| | tools_list | List all 39 available tools with descriptions |

URL Output

All tool responses that contain a URL — asset, preview, approval, checkout, OAuth/device-flow — are emitted as MCP resource_link content blocks (spec 2025-06-18). The URL is also present in a text block as a labeled plain-text link, so clients that reject resource_link still receive it. Clients must present the URL as a clickable link and never fetch, download, embed, or preview the resource's content.

Troubleshooting

| Symptom | Fix | |---------|-----| | 401 Unauthorized | Credentials expired — delete ~/.komplit/credentials.json and re-auth | | auth_wait_for_login timeout | API server not reachable — verify KOMPLIT_API_URL | | 402 Insufficient credits | Use billing_checkout_link to purchase credits, then poll billing_wait_for_credit | | Tool returns error JSON | Check Komplit API status at {KOMPLIT_API_URL}/health |