身份认证

身份认证

KPainter MCP 当前复用的是 public OpenAPI 的同一套用户级 API Key 语义。

它没有单独再做一套 MCP 账号体系。

MCP 里 Key 从哪里来

每次工具调用显式传 api_key

大多数业务工具都支持一个可选的 api_key 参数。

如果你的 MCP host 本身已经知道当前应该使用哪个用户的 key，这就是最清晰的做法。

服务端默认 key 回退

如果工具调用里没有传 api_key，服务端会按这个顺序回退：

1. PARTNER_MCP_DEFAULT_API_KEY
2. KGP_API_KEY

这更适合本地开发，或者控制边界非常清晰的单用户场景。

哪些工具需要 Key

• kp_health 不需要鉴权
• kp_me、kp_get_catalog、kp_create_creation、kp_list_creations、kp_get_creation、kp_get_job_status、kp_edit_scene 都需要用户级 API Key

部分辅助 resources 也会依赖服务端默认 key。这对发现和演示有帮助，但在多用户产品里，不应替代显式的逐用户鉴权。

最先该校验什么

先调 kp_me，确认：

• key 有效
• 服务端解析到的是预期用户
• 当前 key 可以管理创作

这就是 MCP 对应的 GET /me。

浏览器前端边界

当前 MCP 不是主站浏览器前端的主鉴权面。

关键边界是：

• 它围绕 API Key，而不是主站 JWT session
• 浏览器直连时还需要自己处理 MCP 会话和工具调用编排
• 技术上可以实验浏览器直连，但当前并不是主推产品路径

如果你在做 KPainter 主站页面，继续用 /kp-app-api/v1/*。

如果你在做自己的产品集成，除非你的宿主本身就是 MCP 原生环境，否则默认还是 OpenAPI 更合适。

常见错误处理

• 缺少 key：显式传 api_key，或配置 PARTNER_MCP_DEFAULT_API_KEY / KGP_API_KEY
• key 无效：提示用户回到 API Key 页面 检查或重新激活
• 权限不足：不要继续创建
• 积分不足：把用户引导回主站处理

Key 管理仍然在主站完成

MCP 不负责激活、重置或失效 key。

这些操作仍应在主站的 API Key 页面 完成。