MCP 接入文档
通过 Model Context Protocol 把 Hanakoi 的角色 / 剧情 / 生成能力接入你的 Claude Code、Claude Desktop 或任意 MCP 客户端。
端点信息
MCP 端点在 API 域名上，不是站点域名。填成站点域名会得到 404 ——Claude 客户端会显示「Couldn't determine the server settings」， 看起来像服务端故障，其实只是域名填错了。
MCP Endpoint（JSON-RPC 2.0 over HTTP）
https://api.hanakoi.ai/api/v1/mcpProtected Resource Metadata（RFC 9728）
https://api.hanakoi.ai/.well-known/oauth-protected-resourceAuthorization Server Metadata（RFC 8414）
https://api.hanakoi.ai/.well-known/oauth-authorization-server获取 API Key
打开 /admin/mcp → API Keys tab，点击「创建 API Key」。
key 以 hk_ 前缀开头， 创建后立即复制明文（仅显示一次，关闭弹窗后无法再次获取）。
客户端配置
Claude Code（CLI）
claude mcp add --transport http hanakoi https://api.hanakoi.ai/api/v1/mcp \
--header "Authorization: Bearer hk_YOUR_API_KEY"Claude Desktop / 通用 mcpServers 配置
{
"mcpServers": {
"hanakoi": {
"type": "http",
"url": "https://api.hanakoi.ai/api/v1/mcp",
"headers": {
"Authorization": "Bearer hk_YOUR_API_KEY"
}
}
}
}Claude.ai（Custom Connector）
打开 Claude.ai → Settings → Connectors → Add custom connector，填入上方 MCP Endpoint URL。 Claude.ai 会通过 Protected Resource Metadata 自动发现 OAuth 流程，跳转到 Hanakoi 授权页后粘贴 API Key（hk_...）， 点击「Authorize & connect」即可。
鉴权方式
MCP endpoint 同时支持两种 Bearer Token：
- OAuth 2.1 access_token（JWT，1 小时有效，30 天 refresh） — Claude.ai connector OAuth flow 产物，推荐方式。
- Hanakoi API Key（hk_... 前缀） — Claude Desktop / Claude Code / 脚本直连场景，直接放 Bearer header。
验证连通性
配置完成后，用 curl 直接调 initialize 验证 API Key 是否生效：
curl -X POST https://api.hanakoi.ai/api/v1/mcp \
-H "Authorization: Bearer hk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'列出所有可用工具：
curl -X POST https://api.hanakoi.ai/api/v1/mcp \
-H "Authorization: Bearer hk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'角色创建与人工确认流程
角色资料、候选图、关系阶段头像和故事都保留人工确认节点；Agent 不应在用户确认前自动绑定图片或创建故事。
- 先询问用户文本语言偏好，再生成不缺字段的完整角色资料与至少一条 opening_suggestions；greeting 可自由书写，也可选用 *旁白* 格式区分旁白与对白，然后调用 create_character 创建无图角色文档。
- 创建成功后调用 get_character，把角色信息打印给用户审阅。
- 再用 generate_media 生成候选角色图；任务完成后必须向用户展示图片或 URL，并等待用户明确确认，未确认不得绑定图片或生成关系阶段图。
- 用户不满意时先询问具体修改意见（风格、外观、服装、构图等）再重新生成；用户确认候选图后，无论该候选图当前是否已有公开 URL，都必须调用一次 upload_image 转存并取得当前 R2_CDN_URL 下的 URL，再在同一次 update_character 中把 upload_image 返回的 URL 写入 display_image_url、stage_avatars.acquaintance[0]、source_image_url。
- 以 source_image_url 为参考图，使用 image_to_image 分别生成 friend、flirty、lover、honeymoon 四个阶段各一张图；每张完成后展示结果，并用完整 stage_avatars 结构更新，支持按用户反馈换图。
- 全部角色字段与图片完成后再次调用 get_character，打印完整角色信息，并询问用户要修改字段、修改图片，还是添加故事；未经用户同意不要自动创建故事。
- 用户同意添加故事后，先讨论或提出故事方案，再使用 create_story_chapter 创建；完成后调用 list_story_chapters 打印故事信息，并询问用户是否需要修改故事的标题、正文、解锁条件、场景头或剧情节拍。
工具清单（42 个）
以下清单由后端 MCP 服务定义（TOOLS 数组）自动生成并保持同步，可直接在客户端里调用。
get_task获取任务状态只读读取异步任务状态。status=2000 表示成功，5xxx 表示失败，其余状态仍在处理中。工具会在服务端最多等待约 25 秒；terminal=false 时稍后再次调用，禁止高频轮询。任务结束后返回全部图片、视频或音频输出。
必填参数：
idlist_models列出底层模型只读列出底层 models 集合中的模型及供应商配置，供 get_model_params 查询参数。generate_media 选择模型时不要直接使用这里的 ID，应调用 list_model_aliases 获取模型别名。
get_model_params获取模型参数只读读取一个底层模型的基础和高级参数定义，例如画幅、时长、帧数与尺寸。modelId 必须来自 list_models；填写 generate_media 前可用它确认模型的特殊输入要求。
必填参数：
modelIdlist_model_aliases列出模型别名只读列出 model_aliases 单一事实源。generate_media 的 modelId 和工作流节点的 model 都必须使用这里返回的别名 ID；请结合 mcp_description、类型、费用与最大参考图数量选择，不要按列表顺序猜测。
list_characters列出角色只读列出当前用户拥有的角色，返回角色 ID、名称、描述、角色图片和状态。需要更新角色、创作章节或绑定生成图片时先用此工具确认角色 ID。
list_locations列出场景只读列出当前用户拥有的场景资产，用于在连续创作中保持地点外观一致。
create_character创建角色文档有副作用 / 扣积分先创建不缺字段的完整无图角色文档，不调用媒体生成模型。调用前必须先询问用户语言偏好，并用 language 明确记录；name、persona 内的全部文本及必填的 opening_suggestions 必须使用该语言。greeting 可自由书写，也可选用 *旁白* 格式区分旁白与对白，服务端不强制格式。创建成功后先展示角色字段，再调用 generate_media 生成候选图并等待用户确认；不要在创建角色前预先生图。display_image_url 仅为旧客户端兼容字段，新流程不应在本次调用中填写。character_id、user_id 与计数器由服务端生成。
必填参数：
namepersonais_minoraudiencevisibilitycategory_idstagslanguageupdate_character更新角色字段有副作用 / 扣积分按部分更新语义修改当前用户拥有的角色业务字段：只覆盖明确提供的字段，未提供的字段保持不变。支持人设、基础文本、策展信息、内容分级、展示图和阶段头像；greeting 可自由书写，也可选用 *旁白* 格式区分旁白与对白，服务端不强制格式。角色 ID 仅用于定位文档，user_id、状态、计数器等系统字段不可修改。所有角色图片 URL 都必须属于当前 R2_CDN_URL，否则整次更新会在任何写入前被拒绝。用户首次确认候选图后，无论候选 URL 是否已经公开，都必须先调用一次 upload_image，并在同一次 update_character 中把 upload_image 返回的 URL 写入 display_image_url、source_image_url 和 stage_avatars.acquaintance[0]；后续阶段图每次更新都要提交包含已有图片的完整 stage_avatars 结构。更新文本前先读取角色并保持原有语言，除非用户明确要求翻译。
必填参数：
idcreate_story_chapter创建故事章节有副作用 / 扣积分为当前用户拥有的角色创建故事章节；这就是角色故事的生成落库工具，不再另设 generate_character_story。标题和正文会经过内容审核。可设置阅读顺序、关系阶段门槛、解锁规则、复合条件、场景头和剧情节拍；整条故事至少保留一个免费或礼物点数章节。
必填参数：
characterIdtitlecontentupdate_story_chapter更新故事章节有副作用 / 扣积分按部分更新语义修改已有故事章节；这就是角色故事的更新工具，不再另设 update_character_story。只覆盖明确提供的字段，condition 传 null 可移除复合门槛；修改标题或正文会重新执行内容审核。
必填参数：
chapterIdlist_story_chapters列出故事章节只读以作者视角列出一个角色的全部章节及完整正文、顺序和解锁条件。编辑章节前先读取当前值，以便提交准确的部分更新。
必填参数：
characterIdpropose_story_outline检查故事大纲只读在写章节正文前提交整条故事的章节门槛与产出关系，静态检查无法产出的标记、顺序倒置和付费死路。此工具不调用模型、不扣积分；检查通过后再用 create_story_chapter 写入正文。
必填参数：
chapterscheck_character_script检查角色剧本只读静态检查已保存角色剧本中的不可达章节、无法满足的标记或物品门槛、循环依赖和纯付费路径。不调用模型、不扣积分，适合每次编辑后执行。
必填参数：
characterIdsimulate_playthrough模拟故事通关只读用四种确定性玩家行为模拟角色故事，报告回合数、被强制推进的剧情节拍和关系值变化。用于判断故事实际游玩节奏；不调用模型、不扣积分。
必填参数：
characterIddelete_story_chapter删除故事章节有副作用 / 扣积分永久删除作者自己的故事章节，操作不可撤销。读者已经解锁的章节不能删除；删除后若只剩积分付费章节也会被拒绝。
必填参数：
chapterIdupsert_character_event创建或更新角色事件有副作用 / 扣积分创建或部分更新角色主动触发的剧情事件。新事件需要标题、开场文本和触发条件；事件对每位读者最多触发一次，且角色不得借事件推销积分、订阅或折扣。
必填参数：
eventIdcharacterIdlist_character_events列出角色事件只读列出作者角色的全部事件，包括已停用事件及其触发条件、开场文本、优先级和启用状态。
必填参数：
characterIddelete_character_event删除角色事件有副作用 / 扣积分永久删除角色事件，操作不可撤销。通常应优先用 isActive=false 停用，以免重新创建同一事件后对读者再次触发。
必填参数：
eventIdupsert_character_post创建或更新角色动态有副作用 / 扣积分创建或部分更新角色时间线动态。新动态必须提供正文；正文会经过内容审核，且不得推销积分、订阅、升级或折扣。隐藏动态时优先设置 visibility=hidden。
必填参数：
postIdcharacterIdlist_character_posts列出角色动态只读列出作者角色最近的时间线动态，包括隐藏项。更新动态前先读取当前内容。
必填参数：
characterIddelete_character_post删除角色动态有副作用 / 扣积分永久删除角色动态，操作不可撤销，相关评论会失去目标。通常应优先将 visibility 设为 hidden。
必填参数：
postIdupsert_character_npc创建或更新配角有副作用 / 扣积分创建或部分更新角色身边的配角资料卡。新配角必须提供名称和关系；每个主角色最多 30 个配角，可用 chapterIds 标记其出现章节。
必填参数：
npcIdcharacterIdlist_character_npcs列出配角只读列出一个角色的全部配角资料卡，包括已停用项。更新配角前先读取当前内容。
必填参数：
characterIddelete_character_npc删除配角有副作用 / 扣积分永久删除配角资料卡，操作不可撤销。通常应优先用 isActive=false 停用，以保留章节关联。
必填参数：
npcIdcreate_location创建场景有副作用 / 扣积分根据文字描述创建场景资产，并异步生成场景图与六格分镜图。会扣除积分，失败自动退款；返回 taskId 后使用 get_task 获取结果。
必填参数：
namedescriptionget_character获取角色详情只读按角色 ID 获取当前用户拥有的完整角色资料，包括 persona、策展信息、内容分级、display_image_url、source_image_url、reference_sheet_url 与五阶段头像。创建或更新角色后应调用此工具，把结果打印给用户审阅，再询问是否修改字段、修改图片或添加故事。
必填参数：
idget_location获取场景详情只读按场景 ID 获取场景图、分镜图、状态和其他完整资料。
必填参数：
idlist_creations列出生成记录只读按时间倒序列出当前用户的单步生成记录，包括类型、提示词、输出 URL 和状态，可用于复用已经完成的图片或视频。
list_categories列出角色分类只读列出平台当前启用的角色分类及 category_id。创建或更新角色的 category_ids 前先调用此工具，禁止猜测分类 ID。
get_credit_balance获取积分余额只读读取当前用户可用积分及订阅信息。可用总额为 daily_credit、subscription_credit 与 onetime_purchase_credit 之和。
upload_image上传图片有副作用 / 扣积分把本地 base64 图片或远程图片转存到 Hanakoi 公开存储并返回当前 R2_CDN_URL 下的稳定 URL。管理员给出参考图时先调用本工具，再把返回 URL 放入 generate_media.imageUrls 执行图生图；创建角色时运营确认候选图后也必须调用本工具一次，即使候选图已有公开 URL，随后只能用本工具返回的 URL 更新角色文档。支持 jpeg、png、webp、gif，单张上限 10MB。
upload_audio上传音频有副作用 / 扣积分把本地 base64 音频或远程音频转存到 Hanakoi 公开存储并返回稳定 URL。支持 mp3、wav、ogg、webm、m4a、aac、flac，单文件上限 50MB。
upload_video上传视频有副作用 / 扣积分把本地 base64 视频或远程视频转存到 Hanakoi 公开存储并返回稳定 URL。支持 mp4、webm、mov、avi、mkv、m4v，单文件上限 200MB。
generate_media生成图片、视频或音频有副作用 / 扣积分执行一次图片、视频或音频生成，也是角色图像生成和抽卡的唯一工具。先用 list_model_aliases 选择别名；外部参考图先经 upload_image 转为稳定 URL；纯文字生图使用 text_to_image，阶段头像使用 image_to_image，并把角色的 source_image_url 放入 imageUrls。任务会扣积分，失败自动退款；返回 taskId 后用 get_task 获取成品。角色候选图完成后必须向用户展示图片或 URL，并等待明确确认，不能自动绑定；用户不满意时先收集风格、外观、服装或构图修改意见再重生成。
必填参数：
modelIdmodelTypecreate_music创作音乐有副作用 / 扣积分根据创意或完整歌词异步生成原创歌曲，可用于后续角色歌曲。任务会扣积分，失败自动退款；角色聊天内生成完成后会自动投递到会话，外部调用可用 get_task 查询。
start_companion_test_run发起测试会话多轮实跑有副作用 / 扣积分仅限管理员（权限码 admin.harness-config）。为调用者本人创建一个隐藏且隐身的测试会话，按 turns 顺序对指定角色发起真实对话：立即返回 runId 与 sessionId，不等待模型；每一轮由上一轮生成完成的事件驱动下一轮，任一轮失败即终止。每轮都是一次真实模型调用，会产生模型费用，费用由平台承担（billing_owner=platform），不扣管理员积分；最多 10 轮，每轮 ≤ 2000 字符。测试会话使用独立记忆池，不计入社区统计、热度、角色 KPI 与每日指标；内容安全、age-gate 与审核照常生效。之后用 get_companion_test_run 读取结果，不要高频轮询。
必填参数：
characterIdturnsget_companion_test_run读取测试会话实跑结果只读仅限管理员（权限码 admin.harness-config）。只读返回测试运行的状态（queued / running / completed / failed）、逐轮 generationId、终态、角色回复、快捷回复及来源、turn trace 摘要（扩展产出与触发、重复检测、采样、快捷回复补全、请求形态修复）、最后的会话状态字段与平台承担的费用汇总。非发起者的管理员读取会写入管理员审计日志。
必填参数：
runIdlist_companion_llm_calls查询原始模型调用日志只读仅限管理员（权限码 admin.llm-call-logs）。按 sessionId 或 generationId 分页读取角色聊天实际发给模型的请求与 Provider 原始响应 / 错误（凭据与隐藏推理已脱敏）。除角色回复外，同一会话内的 judge、快捷回复补全、关系评估、上下文压缩等非回复调用也可读，每条带 purpose 区分，可用 purpose 入参只看某一类；回复调用额外返回 wireBody（与 Provider 实发 body 同源，含采样字段）。每次读取前先写入管理员审计日志，审计写入失败则拒绝读取；日志来源为 Cloud Logging，未配置时返回不可用。翻页时透传上一页的 nextCursor、queryFrom、queryTo。
preview_companion_request预览角色聊天请求只读管理员专用（需 admin.harness-config 权限）：给定角色、聊天模型、合成历史与本轮消息，返回生产执行器会发给模型的完整请求体（与实发 body 同构，不含凭据）及组装明细：system 分段、本轮上下文落点、各上下文扩展的注入与触发判定、宏、请求形态修正、采样参数与工具列表。不调用模型、不写库、不读取任何真实会话；记忆默认为空，可用 sessionState.memory 注入合成记忆。
必填参数：
characterIduserMessagerun_companion_eval发起角色陪伴评测有副作用 / 扣积分仅限管理员（权限码 admin.harness-config）。对指定角色跑一组评测场景（scenarioIds 或 tags 二选一，都省略则跑整个场景库）：每个场景为调用者本人建一个隐藏且隐身的测试会话，由模拟用户按场景剧本与角色真实对话（第 1 轮也由模拟用户生成，逐字台词原样发送），每一轮由上一轮生成完成的事件驱动下一轮，用户离开或到达轮数上限（每场景最多 30 轮）即结束，随后由 Claude 行为评审逐轮与整会话打分（每项须附角色原文引文）并做 P0 配置保真 lint。立即返回 evalId，不等待任何模型；之后用 get_companion_eval 读取，不要高频轮询。所有模型调用（角色回复、模拟用户、评审）都会产生模型费用，费用由平台承担（billing_owner=platform），不扣管理员积分；测试会话使用独立记忆池，不计入社区统计、热度、角色 KPI 与每日指标；内容安全、age-gate 与审核照常生效。
必填参数：
characterIdget_companion_eval读取角色陪伴评测结果只读仅限管理员（权限码 admin.harness-config）。只读返回评测状态（running / completed / failed）与进度、每个场景的测试会话 id、逐轮对话、评分卡（逐轮 + 整会话、每维度 1–5 分与证据引文、rubric 版本、套路句重复统计）、跨场景维度均值、P0 保真 lint 报告（调用日志不可用时标 unavailable）、角色 prompt rev 与 harness settings rev，以及平台承担的成本汇总。原始模型交换可用 list_companion_llm_calls 按 sessionId 读取。非发起者的管理员读取会先写入管理员审计日志，审计写入失败则拒绝读取。
必填参数：
evalIdcompare_companion_eval对比两次角色陪伴评测只读仅限管理员（权限码 admin.harness-config）。对比同一场景集在两个 revision 上的评测（baseEvalId = 基线，candidateEvalId = 候选）：输出逐维度与逐场景差值、显著退步项（维度均值下降超过阈值，阈值可配置，缺省 0.5 分）及两侧证据引文；合规维度只要候选侧有任何一次失败即判退步。rubric 版本或场景版本不同的评分卡不可直接对比，直接报错。只读；非发起者读取会写入管理员审计日志。
必填参数：
baseEvalIdcandidateEvalId