跳到主要内容

MCP 认证与配置操作手册

最近更新 2026/09/15

MCP 认证与配置操作手册​

编写日期：2026-07-02 适用范围：te-claude 页面端 MCP 管理、会话使用、工作空间 .mcp.json 物化、Slack / 飞书 / Lark / 钉钉等协作类 MCP 接入。

1. 总体原则​

te-claude 的 MCP 接入分为两条链路：

  1. 页面端会话链路：用户在 MCP 管理页配置 MCP，凭证保存在 te-claude DB 中；会话运行时按用户、公司、系统可见性解析 MCP 并注入凭证。
  2. 沙箱 / 工作空间链路：工作空间 .mcp.json 只物化可安全落盘的 MCP 配置；OAuth token、App Secret、敏感 Header 不写入 .mcp.json，敏感 MCP 通过 managed helper/proxy 间接获取运行时配置。

因此：

  • 页面端会话不依赖工作空间 .mcp.json。
  • .mcp.json 主要服务“我的沙箱”里的 Claude Code / 终端工具。
  • 页面端 OAuth 凭证与 Claude Code 本机 OAuth 凭证不会自动互通。
  • 用户第一次使用 OAuth MCP 时需要认证；后续会话复用 DB 中的凭证。
  • 凭证过期或被上游判定失效时，MCP 状态变为“需重认”，不应自动禁用 MCP。

2. 支持的传输方式​

传输方式适用场景页面端自定义 MCP连接模板说明
streamable-http新版远程 MCP、钉钉 MCP、Slack hosted MCP支持支持推荐优先使用。Claude Code 也能识别该类型，不需要转成 http。
http兼容部分远程 MCP支持视模板而定适合服务端 HTTP MCP。
sse旧式 SSE MCP支持视模板而定适合仍使用 SSE transport 的 MCP。
stdio本地/托管命令型 MCP，如飞书/Lark OpenAPI MCP自定义模式不开放支持普通用户不直接填写 command/args；通过连接模板生成 managed helper 配置。

自定义 MCP 默认只开放 URL 型 MCP：sse、http、streamable-http。stdio 只通过受控连接模板进入，避免用户手写命令、路径和密钥导致不可控风险。

3. 支持的认证类型​

认证类型适用 MCP配置方式凭证保存过期处理
Header 手动认证普通私有 MCP、钉钉 URL 型 MCP、部分自建网关Header 行编辑器填写 key/value，可选择加密保存普通 Header 随配置保存；加密 Header 存入 secretJson由用户更新 Header 或 URL
OAuth 2.0Slack hosted MCP、支持标准 OAuth 的远程 MCP配置 OAuth Client ID/Secret、scopes、授权地址、Token 地址、resource 等用户 OAuth token 加密存入 McpCredentialtoken 过期或 invalid_token 时触发重新认证
App Secret飞书 OpenAPI MCP、Lark OpenAPI MCP连接模板填写 App ID、App Secret、toolsApp Secret 加密存入 secretJsonApp Secret 失效时管理员更新配置
无需额外认证URL 中已包含临时 key 的 MCP，如部分钉钉 MCP 网关 URLURL 本身携带 keyURL 按普通配置保存URL/key 失效时重新复制钉钉生成的 URL

Header 行编辑器规则​

MCP 表单中 Headers 使用统一行编辑器：

  • 每行包含 key、value、加密保存、添加按钮、删除按钮。
  • key 必填，必须符合 HTTP Header token 格式，不能包含空格、冒号或控制字符。
  • value 必填；如果要删除 Header，删除整行。
  • Header key 按大小写不敏感去重，Authorization 和 authorization 视为重复。
  • 开启“加密保存”后 value 会加密存储。
  • 编辑已有加密值时，******** 表示保留原值；如果改成 *、*********、1 等，都按真实新值保存。

4. OAuth MCP 通用认证流程​

OAuth MCP 的目标是：用户首次使用时触发认证，认证完成后 te-claude 保存用户凭证，后续会话自动注入凭证。

4.1 配置阶段​

管理员或用户创建 OAuth MCP 时，需要配置：

  • 服务名称：英文 runtime name，例如 slack。
  • 显示名：可中文，例如 Slack MCP。
  • 传输方式：通常为 streamable-http 或 http。
  • 服务地址：MCP endpoint，例如 https://mcp.slack.com/mcp。
  • OAuth Client ID。
  • OAuth Client Secret。
  • scopes。
  • 授权地址。
  • Token 地址。
  • OAuth resource（如服务方要求）。

普通用户不需要填写 providerKey。providerKey 是系统内部字段，只能由系统模板或连接模板写入。

4.2 回调地址​

OAuth 回调地址必须使用 te-claude 当前部署域名，不能使用 localhost。

格式：

https://<te-claude-host>/<basePath>/api/mcp-auth/callback

如果部署有 base path，例如 /agent，则示例为：

https://example.com/agent/api/mcp-auth/callback

服务方后台配置的 redirect URI 必须与 te-claude 发起认证时使用的 redirect URI 一致。

4.3 用户首次使用​

当用户在会话中选择 OAuth MCP：

  1. te-claude 检查该用户是否已有有效凭证。
  2. 如果未认证或需重认，发送前阻断本次消息。
  3. 页面打开 OAuth 认证窗口。
  4. 用户在服务方完成授权。
  5. 服务方回调 te-claude callback。
  6. te-claude 保存 token，并把认证窗口显示为轻量成功页或自动关闭。
  7. 主页面轮询认证状态，刷新 MCP 状态为“已认证”。
  8. 用户重新发送消息，运行时注入 MCP。

4.4 凭证过期与重新认证​

OAuth 凭证可能会过期，常见原因包括：

  • access token 到期。
  • refresh token 到期或被撤销。
  • 用户在服务方取消授权。
  • 服务方返回 invalid_token。
  • 管理员调整了 OAuth App scopes 或权限。

处理策略：

  • 过期或失效时，te-claude 将 MCP 标记为“需重认”。
  • “需重认”不等于禁用；MCP 仍可在会话里被选择。
  • 再次发送时触发认证窗口。
  • 只有用户主动关闭 MCP 或断开认证，才视为禁用。

5. Slack MCP 配置​

Slack 使用官方 hosted MCP：

https://mcp.slack.com/mcp

Slack 通过 连接模板 接入。创建者需要配置自己的 Slack App OAuth Client ID / Client Secret / scopes；每个使用者首次使用时完成个人 OAuth 授权。

Slack OAuth App 与 workspace / customer 强相关。公司级 Slack MCP 通常使用公司统一维护的 Slack App；个人级 Slack MCP 通常用于个人测试或个人 workspace 接入。

推荐使用方式：

创建范围适用场景认证体验
公司 MCP公司统一维护 Slack App，供同公司用户使用公司管理员创建模板配置；每个用户首次使用时各自完成 OAuth 授权。
个人 MCP个人测试或个人 workspace 接入用户创建成功后可立即前往认证，也可首次使用时再认证。

5.2 Slack App 后台配置​

需要在 Slack App 后台确认：

  • 已创建 Slack App。
  • 已配置 OAuth redirect URL：
https://<te-claude-host>/<basePath>/api/mcp-auth/callback
  • scopes 覆盖实际要使用的 Slack 工具。
  • Slack App 已开启 MCP / App Assistant 相关能力。
  • 不建议把静态 xoxp token 当作长期方案写入 Header。

5.3 te-claude 配置​

系统 MCP 建议配置：

在 MCP 管理页选择：

连接模板 -> Slack MCP

模板固定或建议配置：

字段示例
服务名称slack
显示名Slack MCP
传输方式streamable-http
认证模式OAuth 2.0
URLhttps://mcp.slack.com/mcp
OAuth Client IDSlack App 的 Client ID
OAuth Client SecretSlack App 的 Client Secret
scopes按实际需要选择 Slack MCP 工具权限

Slack MCP 的 OAuth Client ID / Client Secret 存储在当前 MCP 实例的加密配置中。Slack Channel 配置用于 IM 渠道绑定；Slack MCP 配置用于 MCP 工具认证，两者独立管理。

用户使用时：

  1. 在会话中选择 Slack MCP。
  2. 如果未认证，页面自动触发 OAuth。
  3. 认证完成后重新发送消息。

如果创建的是个人 Slack MCP，保存成功后 te-claude 会询问是否立即前往 Slack 认证；选择“稍后”不会影响配置，后续首次使用时仍会触发认证。

6. 飞书 OpenAPI MCP 配置​

飞书目前推荐走 OpenAPI MCP 连接模板，由管理员或用户配置自建应用的 App ID / App Secret 和工具列表。

6.1 创建飞书自建应用​

在飞书开放平台创建企业自建应用：

  1. 创建应用，记录 App ID 和 App Secret。
  2. 开启机器人能力。
  3. 设置应用可见范围。
  4. 配置通讯录授权范围。
  5. 按实际工具列表申请 OpenAPI 权限，可见实例6.3 示例工具列表、6.4 工具与权限对应表。
  6. 发布应用并等待权限生效。
  7. 如果你使用用户 OAuth / UAT 路线，另需配置 redirect URL；OpenAPI App Secret 模板本身通常不依赖用户 OAuth redirect。

6.2 te-claude 连接模板​

在 MCP 管理页选择：

连接模板 -> 飞书 OpenAPI MCP

需要填写：

字段说明
服务名称英文 runtime name，例如 feishu-openapi
显示名例如 飞书 OpenAPI MCP
App ID飞书自建应用 App ID
App Secret飞书自建应用 App Secret
工具列表逗号分隔的 OpenAPI 工具名或 preset

模板固定：

字段固定值
传输方式stdio
认证模式应用密钥
分类开发者工具

6.3 示例工具列表​

如果目标是“创建群、拉责任人、发送报告、读取消息、沉淀多维表格”，可从以下工具中选择：

im.v1.chat.create,
im.v1.chat.list,
im.v1.chatMembers.get,
im.v1.message.create,
im.v1.message.list,
wiki.v2.space.getNode,
wiki.v1.node.search,
docx.v1.document.rawContent,
drive.v1.permissionMember.create,
docx.builtin.import,
docx.builtin.search,
bitable.v1.app.create,
bitable.v1.appTable.create,
bitable.v1.appTable.list,
bitable.v1.appTableField.list,
bitable.v1.appTableRecord.search,
bitable.v1.appTableRecord.create,
bitable.v1.appTableRecord.update,
contact.v3.user.batchGetId

也可以先用较宽的 preset：

preset.default,preset.im.default,preset.doc.default

生产使用时建议改为显式工具列表，便于权限审计和风险控制。

6.4 工具与权限对应表​

API 名称功能描述所需权限
im.v1.chat.create创建群创建群（im:chat:create）
im.v1.chat.list获取用户或机器人所在的群列表获取与更新群组信息（im:chat）
im.v1.chatMembers.get获取群成员列表获取与更新群组信息（im:chat）
im.v1.message.create发送消息获取与发送单聊、群组消息（im:message）
im.v1.message.list获取会话历史消息获取与发送单聊、群组消息（im:message）
wiki.v2.space.getNode获取知识空间节点信息查看、编辑和管理知识库（wiki:wiki）
wiki.v1.node.search搜索 Wiki查看知识库（wiki:wiki:readonly）
docx.v1.document.rawContent获取文档纯文本内容创建及编辑新版文档（docx:document）
drive.v1.permissionMember.create增加协作者权限查看、编辑和管理知识库（wiki:wiki）
docx.builtin.import导入文档，包括上传素材/文件、创建导入任务、查询导入任务结果查看、评论、编辑和管理多维表格（bitable:app）；查看、评论、编辑和管理云空间中所有文件（drive:drive）；查看、创建云文档导入任务（docs:document:import）
docx.builtin.search搜索云文档查看、评论、编辑和管理云空间中所有文件（drive:drive）
bitable.v1.app.create创建多维表格查看、评论、编辑和管理多维表格（bitable:app）
bitable.v1.appTable.create新增一个数据表查看、评论、编辑和管理多维表格（bitable:app）
bitable.v1.appTable.list列出数据表查看、评论、编辑和管理多维表格（bitable:app）
bitable.v1.appTableField.list列出字段查看、评论、编辑和管理多维表格（bitable:app）
bitable.v1.appTableRecord.search查询记录查看、评论、编辑和管理多维表格（bitable:app）
bitable.v1.appTableRecord.create新增记录查看、评论、编辑和管理多维表格（bitable:app）
bitable.v1.appTableRecord.update更新记录查看、评论、编辑和管理多维表格（bitable:app）
contact.v3.user.batchGetId通过手机号或邮箱获取用户 ID通过手机号或邮箱获取用户 ID（contact:user.id:readonly）

6.5 常见限制​

  • 工具存在不代表权限已生效，飞书应用必须申请并发布权限。
  • 通讯录 API 还受应用可见范围和通讯录授权范围限制。
  • contact.v3.user.batchGetId 只能通过手机号或邮箱换用户 ID，不是按姓名模糊搜索。
  • 创建群、发送消息等动作通常要求机器人能力已开启。
  • 机器人需要在目标群内，或应用具备对应群操作权限。

7. Lark OpenAPI MCP 配置​

Lark OpenAPI MCP 与飞书 OpenAPI MCP 同构，区别是国际版开放平台域名不同。

te-claude 的 Lark 模板会自动追加：

["--domain", "https://open.larksuite.com"]

用户不需要手动填写 domain。

配置步骤：

  1. 在 Lark Developer 创建自建应用。
  2. 获取 App ID / App Secret。
  3. 开启 Bot 能力。
  4. 配置应用可见范围和权限。
  5. 申请与工具列表对应的 OpenAPI 权限。
  6. 在 te-claude 选择 Lark OpenAPI MCP 连接模板。
  7. 填写 App ID、App Secret、tools。

建议服务名称：

lark-openapi

示例工具列表可复用飞书 OpenAPI MCP 的工具名。权限名称以 Lark Developer 后台实际展示为准。

8. 钉钉 MCP 配置​

钉钉 MCP 当前推荐按 URL 型连接模板 接入，因为钉钉 MCP 广场里存在多个 MCP，名称和 URL 都由钉钉生成，不应在 te-claude 中固定。

8.1 在钉钉 MCP 广场开通​

入口：

https://aihub.dingtalk.com/#/mcp

在钉钉 MCP 广场选择需要的 MCP，例如“机器人消息”“钉钉群聊”等，开通后复制配置 JSON。

示例：

{
  "mcpServers": {
    "机器人消息": {
      "type": "streamable-http",
      "url": "https://mcp-gw.dingtalk.com/server/2de***"
    }
  }
}

8.2 在 te-claude 中配置​

在 MCP 管理页选择：

连接模板 -> 钉钉 MCP

模板固定：

字段固定值
传输方式streamable-http
认证模式Header 手动认证
分类开发者工具

用户需要填写：

字段示例说明
服务名称dingtalk-robot-message必须英文、数字、下划线或连字符；作为 runtime name。
显示名机器人消息可使用钉钉 JSON 中 mcpServers 下的中文 key。
服务地址https://mcp-gw.dingtalk.com/server/2de***复制钉钉生成的 url。

如果钉钉 URL 中已经包含 key，通常不需要额外 Header。该 URL 应视为敏感信息，不要公开粘贴到文档、Issue 或代码仓库。

8.3 钉钉常见限制​

  • 钉钉群聊 MCP 可能要求成员为本企业用户。
  • 创建群、发送消息受企业安全策略限制。
  • 部分 MCP 需要配合通讯录能力把姓名解析为钉钉 userId。
  • URL 或授权失效时，需要回钉钉 MCP 广场重新生成配置。

9. 飞书远程 MCP 暂不作为连接模板​

飞书远程 MCP 需要用户自行获取以下 Header 之一：

  • X-Lark-MCP-UAT：用户身份 token。
  • X-Lark-MCP-TAT：应用身份 token。

同时还需要：

  • Content-Type: application/json
  • X-Lark-MCP-Allowed-Tools

这条路径的 token 获取、刷新、权限诊断门槛较高，当前暂不作为 te-claude 连接模板提供。

如确需使用，可按普通自定义 URL MCP 手动配置：

字段示例
传输方式streamable-http
服务地址https://mcp.feishu.cn/mcp
HeaderX-Lark-MCP-UAT 或 X-Lark-MCP-TAT
HeaderX-Lark-MCP-Allowed-Tools

但产品化优先建议仍是飞书 / Lark OpenAPI MCP。

10. 创建范围与权限​

创建范围可见性谁可以创建适用场景
系统 MCP全站可见系统 seed / 管理员预置不依赖客户私有 OAuth App / App Secret 的全局预置 MCP。
公司 MCP同公司可见公司管理员飞书/Lark OpenAPI 这类公司级 App Secret。
个人 MCP仅本人可见所有登录用户个人测试、个人钉钉 URL、个人 OAuth MCP。

连接模板入口对所有登录用户可见。非管理员可以用模板创建个人 MCP；创建公司级 MCP 仍需要管理员权限。

11. 工作空间 .mcp.json 规则​

工作空间保存 MCP 时，te-claude 会根据 MCP 类型生成 .mcp.json：

11.1 普通 URL MCP​

普通非敏感 URL MCP 可直接写入：

{
  "mcpServers": {
    "dingtalk-robot-message": {
      "type": "streamable-http",
      "url": "https://mcp-gw.dingtalk.com/server/2de***"
    }
  }
}

11.2 托管 MCP​

OAuth、App Secret、敏感 Header MCP 不写明文凭证，而写 managed helper：

{
  "mcpServers": {
    "slack": {
      "type": "stdio",
      "command": "node",
      "args": ["/app/dist/mcp/managed-mcp-remote.js", "--server-id", "system-mcp-slack"]
    }
  }
}

飞书/Lark OpenAPI MCP 也会写 helper，而不是把 App Secret 写入文件。

12. 常见问题排查​

12.1 会话里提示“没有 MCP 工具”​

检查：

  • 是否在会话输入框选择了对应 MCP。
  • MCP 是否启用。
  • OAuth MCP 是否已认证或需重认。
  • 工具列表是否能正常加载。
  • 上游 MCP URL 是否可从 te-claude 服务端访问。
  • 对飞书/Lark OpenAPI，App 权限是否已申请并发布。

12.2 查看工具列表失败​

常见原因：

  • URL 写错。
  • 服务端网络不可达，例如 ECONNREFUSED、ENOTFOUND、ETIMEDOUT。
  • 上游返回 HTML，而不是 MCP JSON-RPC 响应。
  • OAuth token 失效。
  • 飞书/Lark App Secret 错误。
  • 飞书/Lark 工具名不存在或权限不足。

网络不可达不是认证问题，应先确认 te-claude 部署环境是否能访问对应 MCP 地址。

12.3 飞书/Lark 工具存在但调用失败​

检查：

  • 应用是否发布。
  • 权限是否审批通过。
  • 机器人能力是否开启。
  • 应用可见范围是否覆盖目标用户。
  • 通讯录授权范围是否覆盖目标用户。
  • 机器人是否在目标群内。
  • 工具列表是否包含实际调用的 OpenAPI 工具名。

12.4 钉钉 MCP 能保存但调用失败​

检查：

  • 是否复制了完整 URL。
  • URL 中的 key 是否过期。
  • 组织安全策略是否允许对应动作。
  • 创建群或发单聊是否需要钉钉 userId。
  • 对应 MCP 是否已在钉钉 MCP 广场开通。

12.5 Slack 认证成功后仍提示失效​

检查：

  • Slack App redirect URL 是否等于 te-claude callback。
  • Slack App 是否开启 MCP / App Assistant 相关能力。
  • scopes 是否满足工具调用。
  • 用户是否撤销授权。
  • 是否使用了旧 token 或静态 token 方案。
  1. Slack MCP：验证通用 OAuth MCP、用户认证、凭证过期重认。
  2. 飞书 OpenAPI MCP：验证国内 IM / 文档 / 多维表格企业流程。
  3. Lark OpenAPI MCP：验证国际版 Lark 企业客户。
  4. 钉钉 URL 型 MCP：验证钉钉 MCP 广场生成 URL 的接入体验。
  5. 普通自定义 MCP：覆盖客户自建 MCP 和第三方 MCP。

14. 最小验收清单​

配置一个 MCP 后，至少验证：

  • MCP 管理页能保存配置。
  • 工具列表能正常读取，或错误能明确说明原因。
  • 会话中能选择该 MCP。
  • 未认证 OAuth MCP 会触发认证窗口，而不是直接让 Agent 回复“没有工具”。
  • 认证完成后 MCP 状态变为已认证。
  • 工作空间 .mcp.json 不包含 OAuth token、App Secret、敏感 Header 明文。
  • 飞书/Lark OpenAPI MCP 的工具列表与应用权限匹配。
  • 钉钉 MCP 的服务名称为英文，显示名可使用中文。

相关页面与下一步

  • 查找可用工具服务：MCP。
  • 把工具配置到 Agent：Agent。
  • 在会话中使用工具：会话。
  • 配置聊天机器人渠道：渠道管理。
这篇文档对你有帮助吗？
本页内容