KPainter

Quickstart

This example connects KPainter MCP over local stdio and creates a first result.

1. Prepare an API Key

2. Configure stdio

When kp-mcp is installed:

{
  "mcpServers": {
    "kpainter": {
      "command": "kp-mcp",
      "args": ["--stdio"],
      "env": {
        "KGP_API_KEY": "<your_api_key>"
      }
    }
  }
}

From the kgp-service source directory:

{
  "mcpServers": {
    "kpainter": {
      "command": "python",
      "args": ["-m", "src.mcp_server", "--stdio"],
      "cwd": "/path/to/kgp-service",
      "env": {
        "KGP_API_KEY": "<your_api_key>"
      }
    }
  }
}

3. Read Capabilities

Call kp_capabilities first. Confirm that:

• the account is available
• products includes the intended result
• file, video, image, or app settings come from this response

4. Create a First Result

Call kp_create:

{
  "type": "video",
  "prompt": "Explain the customer escalation process to new employees",
  "max_credits": 300,
  "video": {
    "duration_seconds": 120,
    "aspect_ratio": "16:9",
    "language": "en"
  }
}

For source files, call kp_upload_file first and put each returned file_id in input_file_ids.

5. Poll and Read Outputs

• Call kp_get periodically.
• Continue waiting during planning or producing.
• Call kp_outputs after ready.
• When paused, inspect available_actions instead of creating a duplicate.
• When failed, show a clear reason and a useful next step.

6. Refine a Video

Pass this shape to kp_message:

{
  "creation_id": "creation_xxx",
  "content": "Keep everything else and make the second scene easier to understand",
  "idempotency_key": "video-edit-20260901-001"
}

Continue polling the same creation with kp_get.

Read Next

• Transport modes
• Available tools
• Explainer Video