MCP 服务作者与兼容性

MCP 服务可提供 tools、prompts、resources。连接与使用教程见MCP 入口；本页聚焦服务作者需要核对的客户端契约。

发现与工具命名

Qwen 连接 stdio、SSE 或 Streamable HTTP 后分别发现能力，再注册工具包装器。当前 DiscoveredMCPTool 按 mcp____ 生成模型侧名称；发送回服务端的仍是原始工具名。

开发者文档旧段落称“第一个保留无前缀名，冲突者才加 serverName__”，与当前实现不同。不要据旧命名拼权限规则，应从实际发现结果取 canonical 名。经过清理、截断或冲突处理的名字也不能简单反推原始身份。

同样，“没有工具就关闭连接”是旧概述。当前发现路径在没有 prompts、resources、tools 且无被可见性过滤的工具时才视为失败；只提供提示或资源的服务可以有效连接。

Schema 与执行

工具参数使用有效 JSON Schema。客户端存在 provider/schema compliance 适配，不应假设旧文档列出的所有字段始终被剥除；先用目标模型配置检查最终工具声明。

开发文档列出 schemaCompliance:auto 默认透传，以及 openapi_30 对 nullable、const、exclusive limits 等做转换。已有 modelProviders 条目的生成设置应放在该条目，见生成配置，不要以为全局值会逐键补入。

断线后的当前调用只有在可信服务、可信工作区且幂等/只读注解满足条件时才可重放；写入是否发生未知时不能靠重试证明没有副作用。服务作者应准确标注，但管理员仍需核验，见MCP 可靠性。

多内容结果

CallToolResult 的 content 为数组，可混合 text、image、audio、resource、resource_link。文本用于函数结果，媒体按支持路径送模型；单个工具可以同时返回说明和图像，而不是把 base64 放进普通文字。

{
  "content": [
    {"type": "text", "text": "Image generated successfully."},
    {"type": "image", "mimeType": "image/png", "data": "BASE64_IMAGE_BYTES"}
  ]
}

示例 base64 是占位符，需替换真实编码。模型能否处理相应模态与终端能否显示图像是不同问题，见终端图像；返回 HTML App 还有独立资源限制。

Prompts 与参数

服务端注册 prompt 及参数后，用户可调用发现出的斜杠命令，例如 /poem-writer --title="Qwen Code" --mood="reverent"，也可用位置参数。客户端发 prompts/get，由服务端填模板返回消息，再交给模型。

prompt 返回内容不等于客户端本地命令已执行。命名冲突和引用资源的规则见MCP 提示与资源。

Google 身份

authProviderType 默认为 dynamic_discovery。google_credentials 使用 ADC，需在 oauth.scopes 声明所需 scope；service_account_impersonation 使用 ADC 为指定 targetServiceAccount 和 targetAudience 生成 OIDC ID token，供 IAP 场景认证。

服务账号、调用者的 IAP 访问、Token Creator 权限和 IAM Credentials API 都需按云端实际配置完成；设置字段不会自行创建账号或授予权限。普通 OAuth 回调与磁盘 token 存储见MCP 认证。

调试顺序

/mcp 检查 CONNECTING、CONNECTED、DISCONNECTED；发现状态 COMPLETED 只表示发现过程结束，可能包含服务错误。连接失败先核对 command/args/cwd、执行文件、依赖、网络和认证；已连接但无工具再查能力、列表、过滤和 schema。

--debug 与服务 stderr 可辅助定位。沙箱内失败时检查依赖与挂载是否真的在隔离环境中，不直接扩大 trust 来修复路径或协议错误。连接成功也不证明每项工具已获执行权限。