MCP 服务器

添加和治理 Model Context Protocol 服务器，理解凭据与工具边界。

MCP（Model Context Protocol）服务器为 Bot 提供一组外部工具或资源。Hanori 在服务端管理 MCP 连接，再按 Bot、聊天、用户和管理员身份把工具组装到 AI 请求中；浏览器端不会直接持有 MCP 凭据。

添加服务器

在面板的 MCP Servers 页面创建配置，填写：

显示名称和远端连接地址；
所需的传输或授权信息；
是否启用，以及允许哪些 Bot 使用；
需要时的工具或资源过滤策略。

保存后先使用面板提供的连接或测试动作，确认服务器能返回能力列表。服务器“已配置”不等于每个聊天都能看到所有工具。

通过 Bot 的 MCP 管理工具启用或移除服务器后，运行实例会在最后一次成功修改约两秒后重启以应用配置；短时间内的连续修改合并处理。停止或显式重启会取消旧的延迟请求，旧实例的晚到操作不会再次重启新实例。服务关停会等待已经开始的延迟重建收尾。

凭据和权限

凭据应由服务端加密保存。OAuth 或 API Key 不要写进系统提示词、RSS 内容、Telegram 消息或公开文档。只有有权管理集成的角色才能查看连接状态和修改配置；普通成员不应看到原始密钥。

带凭据的工具应默认只对管理员或显式允许的聊天开放。尤其要注意写入、发送、删除、创建任务或访问私有数据的工具，它们拥有外部副作用，不能仅靠前端隐藏按钮来保护。

Telegram 链接读取

需要通过用户账号读取 Telegram 消息或频道链接时，参阅 Telegram 链接读取。该指南说明独立 Reader 的配置与 OAuth 验收，以及当前 Bot 侧尚未完成的接入边界；不是在此页面填入 URL 即可启用的内置功能。

图片 MCP

图片生成可以连接专用图片 MCP 服务。管理面板可能提供单独的授权入口和连接状态页面；这类连接通常只允许 owner 执行 OAuth，其他管理员负责查看或使用已连接状态。授权回调地址必须与实例公开 origin 完全一致。

断开或重新发起授权后，旧连接的授权回调和令牌刷新会失效，不能恢复旧凭据或覆盖新的连接状态。断开连接不会撤销已经提交到远端的图片任务；需要时先核对任务状态。

先部署自己的 MCP Platform，再以 owner 身份打开任意 Bot 的 用量与生图治理 → 图片 MCP 平台。在「平台地址」中填写 mcp.example.com 或 https://mcp.example.com，点击 保存平台地址 即可生效，无需修改环境变量或重新部署。

这个地址保存在数据库中，由所有 Bot 共享。系统自动使用 HTTPS，并分别连接 /mcp/pixai、/mcp/openai-image 和 /mcp/gemini-image。只填写站点地址，不要附加接口路径、登录凭据、查询参数或片段。清空后保存会关闭三个图片 MCP 连接，通用 MCP 服务器和其他功能不受影响。

在 MCP Platform 中配置供应商凭据，再在 Hanori 的三个连接卡片中分别完成 OAuth 授权。保存地址不会自动授予供应商权限；Hanori 不需要复制 Platform 的主密钥、数据库或供应商 API Key。OAuth 回调均位于 BETTER_AUTH_URL 下，PixAI 使用 /api/image-mcp/oauth/callback，GPT 使用 /api/image-mcp-openai/oauth/callback，Gemini 使用 /api/image-mcp-gemini/oauth/callback。

已有部署在首次保存页面配置前继续读取 PIXAI_MCP_URL、OPENAI_IMAGE_MCP_URL 和 GEMINI_IMAGE_MCP_URL。保存页面配置后，三个连接统一使用页面地址，重启后仍然生效；清空页面配置不会重新启用旧环境变量。保存后完整接口地址未变化的连接保留已有授权。

更换 MCP 地址时，先等待已有生图任务结束。授权凭据绑定到完整 MCP 地址，更换后会清除受影响连接的旧授权，旧地址的 token、客户端注册和发现结果不会复用于新地址。升级自固定地址版本时，需显式填写原来的 MCP 地址并由 owner 重新授权一次；旧授权不会被自动发送到新配置的服务。

owner 授权期间，已有任务的后台结果查询可能暂时提示未连接，但不会取消当前授权。真正的回调失败仍会报告错误；授权成功后连接状态恢复为已连接。

连接图片 MCP 后，仍需配置图片路由、用量和内容安全检查；GPT / Gemini 的 preset 可选。请按图片、贴纸与媒体的流程先在测试聊天验证。

重连、取消与结果核对

以下规则适用于面板中添加的通用 MCP 服务器。连接失败时，Hanori 在首次尝试之后最多自动重试 10 次，等待时间从 1 秒起指数增长，单次最多 5 分钟。每次连接握手和工具发现合计最多等待 30 秒；成功后重置连续失败次数。耗尽重试后，先修复远端故障，再在面板手动重连。停用、删除连接或关闭进程会停止计划中的重连，旧连接的晚到结果不会覆盖新连接。

停止回复或 Bot 运行时，正在执行的 MCP 请求会收到尽力取消信号；单次工具调用仍有 10 分钟上限。取消单次请求不会关闭其他请求共用的连接。取消不等于撤销：远端可能已经完成写入，也可能忽略取消。

发送前取消标记为 cancelled；未连接或远端明确报告错误标记为 failed；已发送但因断线、取消或超时未拿到确定回执，标记为 unknown（结果待核对）。诊断结果带请求 ID 和工具调用 ID，便于关联现有运行记录。明确失败的诊断文本会保留，并执行脱敏和长度限制。

同一轮对话内，结果未知的写操作会阻止该 MCP 服务后续的自动写入，包括模型换参数再次调用；明确声明 readOnlyHint 的查询仍可用于核对。只应配置可信 MCP 服务，工具声明不替代权限检查。先在远端检查是否已生成资源或完成操作，再由用户明确发起新的请求。不要把“超时”解释成“什么都没发生”，也不要让模型自动补发。当前不提供远端撤销、跨进程去重或自动对账。

排错

连接失败：检查 URL、TLS、网络出口和服务端日志，不要先重新粘贴密钥。
能连接但工具为空：查看服务器能力列表、工具过滤和当前聊天的权限。
工具调用超时：检查远端服务可用性、请求上限和重试策略；避免无界重试。
结果包含秘密：立即停止在公开群使用该工具，审查服务器返回值与日志脱敏，再决定是否继续。

MCP 服务器的协议细节属于外部服务的一部分。本文只描述 Hanori 的集成边界，实际工具名、输入和费用以服务器能力列表为准。

GPT / Gemini 的动态生图参数

在 MCP Platform 为 GPT、Gemini 分别保存供应商连接（协议、Base URL、API key、默认模型），再在 Hanori 授权对应 MCP。GPT / Gemini 不要求创建预设；create_image 的可选 parameters 中，GPT 可传 model、size、quality；Gemini 可传 model、size、aspectRatio 和 imageSize。省略的参数使用平台连接默认值。AI 可读取路由 backendCapabilities 中的默认值和供应商参数说明；支持范围以供应商为准。预设仍可作为快捷配置，显式覆盖参数时遵循平台审批策略。PixAI 保留已有预设流程。

两个用途可以分别选择默认供应商，动漫默认 PixAI。用户明确要求 GPT / Gemini 时，本次请求可选择对应的已启用供应商，另一家的连接继续可用；失败不会自动切换供应商。默认 preset key 留空即可使用连接默认值。