Authentication

KPainter MCP currently reuses the same user-level API key model as the public OpenAPI.

There is no separate MCP account system.

The Two Ways MCP Gets a Key

Per-tool `api_key`

Most business tools accept an optional api_key parameter.

This is the clearest choice when your MCP host already knows which user's key should be used.

Server-side default key

If a tool call omits api_key, the server falls back in this order:

PARTNER_MCP_DEFAULT_API_KEY
KGP_API_KEY

This is useful for local development or for tightly controlled single-user setups.

Which Tools Need a Key

kp_health does not require auth
kp_me, kp_get_catalog, kp_create_creation, kp_list_creations, kp_get_creation, kp_get_job_status, and kp_edit_scene require a user API key

Some helper resources can also rely on the server's default key. That is helpful for discovery, but it should not replace explicit per-user authentication in a multi-user product.

What To Validate First

Call kp_me before creation to confirm:

the key is valid
the server resolved the expected user
the key can manage creations

This is the MCP equivalent of calling GET /me in OpenAPI.

Browser Frontend Boundary

MCP is not currently designed as the main browser frontend auth surface.

Important boundaries:

it is centered on API keys, not the main site's JWT session
browser clients would still need MCP session handling and tool orchestration
browser direct-connect is technically possible, but it is not the recommended primary product path today

If you are building normal KPainter web pages, stay on /kp-app-api/v1/*.

If you are building your own product integration, OpenAPI is still the better default unless your host is already MCP-native.

Common Error Handling

missing key: pass api_key, or configure PARTNER_MCP_DEFAULT_API_KEY / KGP_API_KEY
invalid key: ask the user to re-check or reactivate it on the API Key page
insufficient permission: stop before creation
insufficient credits: route the user back to the main site

Key Management Still Happens On The Main Site

MCP does not activate, rotate, or invalidate keys.

Users should still manage those actions on the main site's API Key page.