> ## Documentation Index > Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt > Use this file to discover all available pages before exploring further. # 远程 MCP 服务器 > 通过内置的 Model Context Protocol（MCP）服务器将 AI 客户端连接到正在运行的知行之桥实例，用于诊断和执行运维操作。 知行之桥 内置了一个 **MCP 服务器**，可将 AI 客户端（例如 Claude Desktop、GitHub Copilot、OpenAI Codex 或任何兼容 MCP 的客户端）直接连接到正在运行的 知行之桥 实例。之后，即可使用自然语言与 知行之桥 交互，询问错误、日志、配置、端口、文件、证书和整体系统运行状况，并执行触发端口、重新排队消息等运维操作。 MCP 服务器默认启用，共提供 18 个工具：15 个诊断工具，以及 3 个对 知行之桥 实例执行操作的操作工具。无需在 知行之桥 UI 中进行任何配置；该功能本身就是供外部 AI 客户端连接的 MCP 服务器端点。 > [!WARNING] > > 使用 AI 助手可能会将 知行之桥 中的数据发送给第三方 AI 服务。请先确认组织的数据处理政策和所用服务的条款。AI 生成的结果可能不准确，应在执行操作前进行验证。如需帮助，请联系 知行软件 技术支持。 如需为 知行之桥 自身配置 AI 提供商（用于产品内的 AI 功能），请参阅 [AI 设置](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/ai-settings.md)。 ## 连接 AI 客户端 MCP 服务器端点为： ``` https://:/mcp.rsc ``` 身份验证使用 `x-cdata-authtoken` 头部和有效的 知行之桥 用户 Authtoken。要生成 Authtoken，请在[用户](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/users.md)页面打开该用户的 **API 访问**选项卡，勾选**启用 Authtoken 访问**，然后复制系统生成的 Authtoken。 ### 安全存储 Authtoken 下面的客户端配置示例将 Authtoken 作为内联值写在配置文件中。这种方式可以正常工作，但共享工作站上的配置文件可能会被其他本地用户读取，或被意外提交到版本控制系统。将令牌存储在操作系统环境变量中，可以避免将其写入配置文件本身。 **Linux 和 macOS** 将以下行添加到 shell 配置文件（`~/.bashrc`、`~/.zshrc` 或 `~/.profile`）中，然后重新加载该文件： ```bash theme={null} export ARC_AUTHTOKEN="your-authtoken" ``` **Windows** 打开命令提示符并运行： ``` setx ARC_AUTHTOKEN "your-authtoken" ``` 此命令会设置一个持久的用户级环境变量。运行该命令后，请重启所有已打开的终端或应用程序，使其读取新变量。 #### 在客户端配置文件中引用变量 **GitHub Copilot CLI** 和 **OpenAI Codex** 客户端都从终端启动，并继承完整的系统环境，因此可以直接读取系统环境变量。各客户端的安全配置方法见下文对应章节。 **Claude Desktop** 不会像从终端启动的进程那样继承完整的系统环境，因此在其配置 JSON 中引用环境变量无效。请改用下文 [Claude Desktop](#claude-desktop) 一节中介绍的 `--header-file` 方法。 保存以下任一配置后，请重启 AI 客户端会话。 ### Claude Desktop Claude Desktop 通过 `stdio` 与 MCP 服务器通信（它会启动一个本地子进程，并通过 `stdin/stdout` 进行通信），因此无法直接连接到 知行之桥 的远程 HTTP 端点。`mcp-remote` npm 包可以弥补这一差距：它作为本地 stdio 进程运行，供 Claude Desktop 与之通信，并将请求转发到 知行之桥 的 HTTP 端点。 `--transport http-only` 标志指示 `mcp-remote` 在与 知行之桥 通信时使用纯 Streamable HTTP，从而跳过任何协商 SSE（Server-Sent Events）的尝试。`mcp.rsc` 端点不支持 SSE，因此该标志可避免不必要的回退延迟或连接错误。 将以下内容添加到 Claude Desktop 配置文件中（**Settings > Developer > Edit Config**）： ```json theme={null} { "mcpServers": { "arc-mcp": { "command": "npx", "args": ["-y", "mcp-remote", "https://:/mcp.rsc", "--transport", "http-only", "--header", "x-cdata-authtoken:"] } } } ``` > [!NOTE] > > 如果使用 Windows，请使用 `"command": "cmd"`，并在 `"npx"` 前添加 `"cmd", "/c"` 前缀。 #### 使用 `--header-file` 引用令牌的替代方法 Claude Desktop 的配置 JSON 不支持引用环境变量，因为它启动子进程时不经过 shell。要避免将 Authtoken 写入配置文件，请改用 `mcp-remote` 的 `--header-file` 标志。 在 Claude Desktop 可以访问的任意位置创建一个纯文本文件（例如 `/home//.cdata/arc-mcp-headers.txt`），并添加以下行： ``` x-cdata-authtoken: ``` 然后限制该文件的权限，使只有当前用户账户可以读取： **macOS 和 Linux**： ```bash theme={null} chmod 600 /home//.cdata/arc-mcp-headers.txt ``` **Windows**（命令提示符）： ``` icacls "C:\Users\\.cdata\arc-mcp-headers.txt" /inheritance:r /grant:r "%USERNAME%:R" ``` 然后更新配置，使用 `--header-file` 代替 `--header`： ```json theme={null} { "mcpServers": { "arc-mcp": { "command": "npx", "args": ["-y", "mcp-remote", "https://:/mcp.rsc", "--transport", "http-only", "--header-file", "/home//.cdata/arc-mcp-headers.txt"] } } } ``` > [!NOTE] > > 如果使用 Windows，请使用 `"command": "cmd"`，在 `"npx"` 前添加 `"cmd", "/c"` 前缀，并使用 Windows 路径，例如 `C:\Users\\.cdata\arc-mcp-headers.txt`（在 JSON 字符串中，每个反斜杠都要写成 \）。 保存后，退出并重新打开 Claude Desktop，然后在新聊天的 **Tools/Search** 菜单中启用 `arc-mcp` 服务器。 ### GitHub Copilot CLI 与 Claude Desktop 不同，GitHub Copilot CLI 可以直接通过 HTTP 连接远程 MCP 服务器，因此不需要 `mcp-remote` 桥接，而是直接指向 知行之桥 端点。其 MCP 配置文件的位置取决于操作系统： | 操作系统 | 配置文件位置 | | - | - | | macOS / Linux | `~/.copilot/mcp-config.json` | | Windows | `C:\Users\\.copilot\mcp-config.json` | 编辑该文件并添加以下内容： ```json theme={null} { "mcpServers": { "arc-mcp": { "url": "https://:/mcp.rsc", "type": "http", "headers": { "x-cdata-authtoken": "" } } } } ``` #### 使用环境变量安全存储令牌 GitHub Copilot CLI 支持在 `headers` 字段中使用 `${VAR}` 替换。将内联的 Authtoken 值替换为对 `ARC_AUTHTOKEN` 变量的引用： ```json theme={null} { "mcpServers": { "arc-mcp": { "url": "https://:/mcp.rsc", "type": "http", "headers": { "x-cdata-authtoken": "${ARC_AUTHTOKEN}" } } } } ``` 启动 Copilot CLI 之前，必须将 `ARC_AUTHTOKEN` 设置为系统或用户环境变量。有关设置说明，请参阅[安全存储 Authtoken](#安全存储-authtoken)。 保存后，启动新的 Copilot CLI 会话，使其加载 `arc-mcp` 服务器。 ### OpenAI Codex 与 Copilot CLI 一样，OpenAI Codex 直接支持远程 HTTP MCP 服务器，因此不需要桥接，可以直接连接到 知行之桥 端点。其配置文件的位置取决于操作系统： | 操作系统 | 配置文件位置 | | - | - | | macOS / Linux | `~/.codex/config.toml` | | Windows | `C:\Users\\.codex\config.toml` | 此配置在 Codex CLI、Codex IDE 扩展和 Codex Desktop 之间共享。编辑该文件并添加以下内容： ```toml theme={null} [mcp_servers.arc-mcp] url = "https://:/mcp.rsc" http_headers = { "x-cdata-authtoken" = "" } ``` #### 使用环境变量安全存储令牌 OpenAI Codex 提供单独的 `env_http_headers` 字段，用于将头部名称映射到环境变量名称，而不是内联值。将 `http_headers` 替换为 `env_http_headers`： ```toml theme={null} [mcp_servers.arc-mcp] url = "https://:/mcp.rsc" env_http_headers = { "x-cdata-authtoken" = "ARC_AUTHTOKEN" } ``` 启动 Codex 之前，必须将 `ARC_AUTHTOKEN` 设置为系统或用户环境变量。有关设置说明，请参阅[安全存储 Authtoken](#安全存储-authtoken)。 保存后，重启 Codex（或启动新会话），使其加载 `arc-mcp` 服务器。 ## 关联 ID 知行之桥 会为从单个入口点开始的工作（入站 HTTP 请求、AS2 或 SFTP 会话、计划触发或 Flow API 调用）标记一个关联 ID（correlation Id），并将其传递到由此产生的交易、应用程序日志条目、请求日志条目和服务日志会话中。下文中的多个诊断工具会在可用时返回此 ID，便于将同一工作单元的相关证据关联起来。 ## 可用工具 ### 诊断工具 以下 15 个工具为只读工具，不会修改 知行之桥 实例上的任何数据或状态。
工具 说明
`find_workspaces`列出并检查 知行之桥 工作区，包括端口摘要以及近期的交易数和错误数。
`find_connectors`按工作区或类型浏览端口；深入查看端口的配置、工作流连接、引用的证书和错误率。
`find_messages`按端口、状态、方向、时间范围或消息 ID 搜索交易消息。检索消息详细信息，包括消息头和交易日志内容。
`find_files`在 Send、Receive 或 Sent 文件夹中搜索端口消息文件。按名称检索文件内容。
`find_logs`按严重级别、时间范围或消息文本查询应用程序日志。在可用时返回关联 ID 字段，用于将日志条目与相关交易和服务日志会话关联起来。
`find_requests`检查 API 请求日志，用于审计和故障排除（可按方法、URL、用户、IP 或时间范围筛选）。在可用时返回关联 ID 字段。
`find_certificates`查找证书、检查到期日期，并按端口使用情况或类别（Public 或 Private）筛选。
`find_vault_entries`按名称、类型或标签搜索配置库条目。加密值永远不会公开。
`find_reports`浏览报告定义，并检查计划、列、筛选器和电子邮件收件人配置。
`find_flow_apis`浏览 Flow API 定义，或获取某个 API 的请求和响应配置。
`find_service_logs`查找端口服务日志（AS2、AS4、GISB、RNIF、FTP Server、OFTP、SFTP Server、TCP Server、AMQP、IDoc、MQTT），并检索某一日志的内容。适用于排查未生成交易记录的连接、监听器和协议级故障。
`diagnose_message`按消息 ID 或交易 ID 诊断特定交易消息。返回完整的消息详细信息（消息头和交易日志内容）。存在关联 ID 时，还会返回该消息相关的请求日志条目、应用程序日志条目和服务日志证据。
`trace_message_flow`在提供消息 ID，或提供文件名和端口时，端到端跟踪消息在工作流中跨端口流转的过程。
`check_health`获取 知行之桥 实例的运行状况快照：错误数、即将到期的证书、许可证状态、内存和磁盘警告，以及各端口的失败率和消息积压情况。
`describe_profile`按分区查看 知行之桥 个人设置（应用程序、AS2、SFTP 等）。机密值会被屏蔽。
### 操作工具 18 个工具中有 3 个会对 知行之桥 实例执行实际操作，而不仅仅是读取数据。运行这些工具之前，AI 客户端会请求您明确确认。以下防护措施适用于全部 3 个工具： * **需要确认。** 未经您事先明确确认，AI 客户端无法执行任何操作。 * **沿用现有权限。** 用户只能触发、重新排队或清理其 知行之桥 权限已允许的资源。只有只读访问权限的用户完全无法调用操作工具。 * **必须指定目标。** 每个操作都会指定其影响的具体工作区和端口，不会推断或猜测任何内容。 * **操作会被审计。** 每个操作都会写入一条审计记录，标明运行了什么操作、针对哪个端口以及结果如何。 要查看或调整权限，请参阅[用户角色](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/user-roles.md)。
工具 说明
`trigger_connector`运行端口的接收或发送操作，可选择针对特定文件或消息。
`requeue_message`将之前已处理的消息重新排队，使端口再次处理该消息，等同于**交易**选项卡上的**重新排队**操作。
`cleanup_files`针对单个端口、单个工作区或所有工作区运行[已配置的批量清理](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/cleanup-settings.md)，归档或删除早于指定天数的数据。
## 示例提示 通过 AI 客户端，可以使用自然语言与 知行之桥 交互。诊断提示示例包括： * “分析消息 EDIFACT1-20260513-123047000-wxcU 的失败原因，并给出修复建议。” * “显示过去 24 小时内所有提到 AS2 的错误日志。” * “哪些证书将在未来 30 天内到期？” * “跟踪消息 AS2\_Inbound-20260623-001 在其工作流中的流转过程。” * “检查生产工作区的运行状况。” * “列出所有 SFTP 端口。” * “显示今天上午各会话的 SFTP Server 服务日志。” 对于操作工具，AI 客户端会在继续之前请求您确认。例如： * **您：** 将 Production 工作区中 AS2\_Outbound 端口上的消息 AS2\_Outbound-20260814-001 重新排队。 * **AI 客户端：** 我将把 Production 工作区中 AS2\_Outbound 端口上的消息 AS2\_Outbound-20260814-001 重新排队。这会使端口再次处理该消息。是否继续？ * **您：** 是。 * **AI 客户端：** 已完成。该消息已重新排队。 ## 安全说明 * MCP 服务器遵循 知行之桥 现有的身份验证和授权机制。用户只能看到其有权访问的数据。 * 请始终通过 HTTPS 连接。每次调用时，`x-cdata-authtoken` 都会在请求头中发送；如果使用纯 HTTP，它会在传输过程中暴露。仅在针对 `localhost` 进行测试时使用 `http://`。 * 工具响应中的敏感值（密码、令牌和私钥）会被屏蔽。 * 永远不会返回加密的配置库条目值。 * 请将 Authtoken 存储在操作系统环境变量中，而不是作为内联值写入客户端配置文件。请参阅[安全存储 Authtoken](#安全存储-authtoken)。 * 操作工具在运行任何操作之前都需要用户明确确认，并且每个操作都会被审计。只有只读访问权限的用户无法调用操作工具。 ## 本版本的已知限制 * 在详细模式下返回的大型消息负载可能较大，可能会影响 AI 客户端的令牌用量。 * 服务日志按会话检索。当一个会话涉及多个文件时，`diagnose_message` 返回的关联证据可能包含同一会话中的其他文件。这是预期行为。 * 关联 ID 覆盖主要的消息处理路径。某些路径（例如某些计划重试工作进程）可能不携带关联 ID。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.