HAP MCP 概览
让 AI 在授权范围内连接明道云应用，查询业务数据、更新记录，并协助完成业务任务。
可接入支持远程 MCP（Streamable HTTP）的主流 Agent 工具。使用个人访问令牌时，还需支持自定义 HTTP 请求头。
MCP（Model Context Protocol，模型上下文协议）是 AI 客户端连接外部工具的开放协议。HAP MCP 将明道云的业务能力提供为可调用的工具。连接后，AI 可以根据你的要求选择工具并发起调用，无需为每个任务单独编写接口集成代码。
可以做什么
了解应用结构：查询应用、工作表和字段，为后续操作准备上下文。
查询和分析数据：按条件查找业务记录，汇总结果并生成分析。
维护业务数据：在授权范围内新增或更新记录。
协助完成任务：组合多个工具调用，处理跨步骤的业务需求。
具体可用工具和可操作数据，以当前凭据的授权范围及客户端实际加载结果为准。
选择访问方式
HAP MCP 提供两种鉴权方式。根据使用场景选择其一，再获取对应配置。
| 个人访问令牌 | 应用密钥 | |
|---|---|---|
| 适用场景 | 让 AI 以个人身份协助处理日常业务 | 让 AI 围绕指定应用进行业务集成 |
| 配置入口 | 工作台「连接 AI」→ 个人 | 工作台「连接 AI」→ 应用，或应用管理 → API 文档 → 应用授权 → MCP |
| 鉴权方式 | 请求头 Authorization: Bearer 个人访问令牌 | URL 参数 HAP-Appkey 和 HAP-Sign |
| 访问范围 | 以个人访问令牌的实际授权范围为准 | 以所选应用密钥的实际授权范围为准 |
连接 MCP 不会扩大凭据的权限。AI 能否执行某项操作，仍取决于当前身份、应用授权及相关权限设置。
开始连接
获取配置：从工作台「连接 AI」或目标应用的 API 文档中获取 MCP 配置。
连接客户端：使用界面提供的一键连接，或将配置添加到支持远程 MCP 的客户端。
验证结果：确认工具加载成功，再执行一次小范围的读取操作。
服务信息
| 项目 | 说明 |
|---|---|
| HAP 公有云服务地址 | https://api.mingdao.com/mcp |
| 连接方式 | 远程 MCP，使用 Streamable HTTP |
| 鉴权方式 | 个人访问令牌或应用密钥 |
Host 是随部署环境变化的变量。 HAP 公有云使用 api.mingdao.com；私有部署使用所在部署环境的 Host。本文 JSON 中的服务地址以 HAP 公有云为例。
私有部署请使用当前环境的「连接 AI」或应用 API 文档生成的完整 MCP 地址。如果部署地址包含路径前缀，也需要保留，不能只替换公有云地址中的域名。
支持远程 MCP 的客户端可直接连接，无需在本地部署 HAP MCP Server。若客户端需要本地代理，再按该客户端要求准备运行环境。
获取配置与连接
从工作台「连接 AI」按提示安装，或获取个人访问令牌、应用密钥配置后手动接入。
以下 JSON 以 HAP 公有云地址为例。Host 随部署环境变化：公有云使用
api.mingdao.com，私有部署使用对应环境的 Host，并保留部署路径前缀（如有）。请以所在环境生成的完整 MCP 配置为准。
通过「连接 AI」接入
在工作台右上角点击连接 AI，打开 MCP 页签。
从工作台右上角打开「连接 AI」，进入 MCP 配置。
选择安装方式：支持对话安装和手动安装。
选择连接工具：选择需要连接的 Agent 工具。列表中没有对应工具时，可选择「其他」。
选择权限范围：选择「个人」时，选择个人访问令牌；选择「应用」时，选择目标应用和授权密钥。
按需安装配套 Skills：可勾选「同时安装配套 Skills」，帮助 AI 理解 HAP 的概念与操作方式。
完成安装：对话安装时点击「安装」，打开目标工具并填入安装提示词，在客户端确认执行；也可复制提示词到 AI 对话中。手动安装时，复制页面生成的命令到终端执行。
按界面依次选择安装方式、连接工具和权限范围，再完成安装。
可选工具和安装内容以当前界面为准。更多说明参见 连接 AI 使用帮助。
个人访问令牌配置
适合让 AI 以你的个人身份协助处理业务。通过「连接 AI」选择「个人」及对应令牌完成安装；需要手动配置客户端时，使用以下结构，通过 HTTP 请求头传递个人访问令牌。
以下示例适用于采用 mcpServers JSON 配置、支持远程 URL 及自定义请求头的客户端。请将占位符替换为实际个人访问令牌；优先使用界面生成的对应客户端配置。
权限、使用建议与排错
确认连接使用的凭据和访问范围，再让 AI 执行业务操作。
权限范围
个人访问令牌：以该令牌的实际授权范围为准，并受个人身份及相关权限设置约束。
应用密钥：以所选密钥的应用授权范围为准。连接前确认所选应用和密钥正确。
可用工具与数据：以客户端实际加载的工具和服务调用结果为准。工具可见不代表对所有目标数据都有操作权限。
授权或应用结构发生变化后，按客户端要求重新连接或刷新工具列表，再验证实际可用范围。
凭据管理
个人访问令牌、应用密钥 URL 都包含访问凭据。不要将其提交到公开仓库，或放入公开文档、截图和日志。分享配置时，用占位符替换令牌、Appkey 和 Sign。
测试与生产使用各自的凭据。凭据失效、泄露或不再需要时，在对应管理入口更新或停用，并同步更新客户端配置。
执行建议
查询应用、工作表和字段结构，确认目标。
读取少量样本，核对筛选条件和字段含义。
修改前说明操作内容、目标范围和预计影响数量。
对批量修改等高影响操作保留人工确认。
执行后再次查询，核对实际结果。
常见问题
连接失败或超时
确认客户端支持 Streamable HTTP，服务已启用，且客户端运行环境能访问目标地址。使用应用密钥时，检查 URL 是否完整；使用个人令牌时，检查客户端是否发送了自定义请求头。云端客户端需要从云端运行环境访问服务。
提示鉴权失败
个人令牌方式检查 Authorization 的值是否为 Bearer 个人访问令牌，中间保留空格，并确认令牌仍有效。应用密钥方式请从 API 文档重新复制所选密钥的 MCP 配置，检查 HAP-Appkey、HAP-Sign 是否完整。
连接成功，但工具或数据与预期不符
先确认连接使用的是哪种凭据、哪个应用及哪组密钥，再检查实际授权范围。按客户端要求刷新工具列表。如果工具已加载但调用失败，继续检查目标工作表、字段权限、输入参数和记录状态。
是否必须安装 Node.js？
HAP MCP 使用远程服务地址。支持直接连接的客户端无需为 HAP MCP 安装 Node.js；只有使用本地代理或其他本地程序时，才按所用组件要求安装对应运行环境。
浏览器直接打开 MCP 地址，能判断连接成功吗？
不能仅凭浏览器页面判断。MCP 客户端需要按协议连接并传递鉴权信息。请以客户端成功加载工具、并完成一次读取操作作为验证依据。
