远程 MCP 服务器

知行之桥内置了一个 MCP 服务器，可将 AI 客户端（例如 Claude Desktop、GitHub Copilot、OpenAI Codex 或任何兼容 MCP 的客户端）直接连接到正在运行的知行之桥实例。之后，即可使用自然语言与知行之桥交互，询问错误、日志、配置、端口、文件、证书和整体系统运行状况，并执行触发端口、重新排队消息等运维操作。 MCP 服务器默认启用，共提供 18 个工具：15 个诊断工具，以及 3 个对知行之桥实例执行操作的操作工具。无需在知行之桥 UI 中进行任何配置；该功能本身就是供外部 AI 客户端连接的 MCP 服务器端点。

使用 AI 助手可能会将知行之桥中的数据发送给第三方 AI 服务。请先确认组织的数据处理政策和所用服务的条款。AI 生成的结果可能不准确，应在执行操作前进行验证。如需帮助，请联系知行软件技术支持。

如需为知行之桥自身配置 AI 提供商（用于产品内的 AI 功能），请参阅 AI 设置。

连接 AI 客户端

MCP 服务器端点为：

https://<baseurl>:<port>/mcp.rsc

身份验证使用 x-cdata-authtoken 头部和有效的知行之桥用户 Authtoken。要生成 Authtoken，请在用户页面打开该用户的 API 访问选项卡，勾选启用 Authtoken 访问，然后复制系统生成的 Authtoken。

安全存储 Authtoken

下面的客户端配置示例将 Authtoken 作为内联值写在配置文件中。这种方式可以正常工作，但共享工作站上的配置文件可能会被其他本地用户读取，或被意外提交到版本控制系统。将令牌存储在操作系统环境变量中，可以避免将其写入配置文件本身。 Linux 和 macOS 将以下行添加到 shell 配置文件（~/.bashrc、~/.zshrc 或 ~/.profile）中，然后重新加载该文件：

export ARC_AUTHTOKEN="your-authtoken"

Windows 打开命令提示符并运行：

setx ARC_AUTHTOKEN "your-authtoken"

此命令会设置一个持久的用户级环境变量。运行该命令后，请重启所有已打开的终端或应用程序，使其读取新变量。

在客户端配置文件中引用变量

GitHub Copilot CLI 和 OpenAI Codex 客户端都从终端启动，并继承完整的系统环境，因此可以直接读取系统环境变量。各客户端的安全配置方法见下文对应章节。 Claude Desktop 不会像从终端启动的进程那样继承完整的系统环境，因此在其配置 JSON 中引用环境变量无效。请改用下文 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）：

{
  "mcpServers": {
    "arc-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote",
        "https://<baseurl>:<port>/mcp.rsc",
        "--transport", "http-only",
        "--header", "x-cdata-authtoken:<your-authtoken>"]
    }
  }
}

如果使用 Windows，请使用 "command": "cmd"，并在 "npx" 前添加 "cmd", "/c" 前缀。

使用 `--header-file` 引用令牌的替代方法

Claude Desktop 的配置 JSON 不支持引用环境变量，因为它启动子进程时不经过 shell。要避免将 Authtoken 写入配置文件，请改用 mcp-remote 的 --header-file 标志。在 Claude Desktop 可以访问的任意位置创建一个纯文本文件（例如 /home/<username>/.cdata/arc-mcp-headers.txt），并添加以下行：

x-cdata-authtoken: <your-authtoken>

然后限制该文件的权限，使只有当前用户账户可以读取： macOS 和 Linux：

chmod 600 /home/<username>/.cdata/arc-mcp-headers.txt

Windows（命令提示符）：

icacls "C:\Users\<username>\.cdata\arc-mcp-headers.txt" /inheritance:r /grant:r "%USERNAME%:R"

然后更新配置，使用 --header-file 代替 --header：

{
  "mcpServers": {
    "arc-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote",
        "https://<baseurl>:<port>/mcp.rsc",
        "--transport", "http-only",
        "--header-file", "/home/<username>/.cdata/arc-mcp-headers.txt"]
    }
  }
}

如果使用 Windows，请使用 "command": "cmd"，在 "npx" 前添加 "cmd", "/c" 前缀，并使用 Windows 路径，例如 C:\Users\<username>\.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\<username>\.copilot\mcp-config.json`

编辑该文件并添加以下内容：

{
  "mcpServers": {
    "arc-mcp": {
      "url": "https://<baseurl>:<port>/mcp.rsc",
      "type": "http",
      "headers": {
        "x-cdata-authtoken": "<your-authtoken>"
      }
    }
  }
}

使用环境变量安全存储令牌

GitHub Copilot CLI 支持在 headers 字段中使用 ${VAR} 替换。将内联的 Authtoken 值替换为对 ARC_AUTHTOKEN 变量的引用：

{
  "mcpServers": {
    "arc-mcp": {
      "url": "https://<baseurl>:<port>/mcp.rsc",
      "type": "http",
      "headers": {
        "x-cdata-authtoken": "${ARC_AUTHTOKEN}"
      }
    }
  }
}

启动 Copilot CLI 之前，必须将 ARC_AUTHTOKEN 设置为系统或用户环境变量。有关设置说明，请参阅安全存储 Authtoken。保存后，启动新的 Copilot CLI 会话，使其加载 arc-mcp 服务器。

OpenAI Codex

与 Copilot CLI 一样，OpenAI Codex 直接支持远程 HTTP MCP 服务器，因此不需要桥接，可以直接连接到知行之桥端点。其配置文件的位置取决于操作系统：

操作系统	配置文件位置
macOS / Linux	`~/.codex/config.toml`
Windows	`C:\Users\<username>\.codex\config.toml`

此配置在 Codex CLI、Codex IDE 扩展和 Codex Desktop 之间共享。编辑该文件并添加以下内容：

[mcp_servers.arc-mcp]
url = "https://<baseurl>:<port>/mcp.rsc"
http_headers = { "x-cdata-authtoken" = "<your-authtoken>" }

使用环境变量安全存储令牌

OpenAI Codex 提供单独的 env_http_headers 字段，用于将头部名称映射到环境变量名称，而不是内联值。将 http_headers 替换为 env_http_headers：

[mcp_servers.arc-mcp]
url = "https://<baseurl>:<port>/mcp.rsc"
env_http_headers = { "x-cdata-authtoken" = "ARC_AUTHTOKEN" }

启动 Codex 之前，必须将 ARC_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 客户端无法执行任何操作。
沿用现有权限。 用户只能触发、重新排队或清理其知行之桥权限已允许的资源。只有只读访问权限的用户完全无法调用操作工具。
必须指定目标。 每个操作都会指定其影响的具体工作区和端口，不会推断或猜测任何内容。
操作会被审计。 每个操作都会写入一条审计记录，标明运行了什么操作、针对哪个端口以及结果如何。

要查看或调整权限，请参阅用户角色。

工具	说明
`trigger_connector`	运行端口的接收或发送操作，可选择针对特定文件或消息。
`requeue_message`	将之前已处理的消息重新排队，使端口再次处理该消息，等同于交易选项卡上的重新排队操作。
`cleanup_files`	针对单个端口、单个工作区或所有工作区运行已配置的批量清理，归档或删除早于指定天数的数据。

示例提示

通过 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。
操作工具在运行任何操作之前都需要用户明确确认，并且每个操作都会被审计。只有只读访问权限的用户无法调用操作工具。

本版本的已知限制

在详细模式下返回的大型消息负载可能较大，可能会影响 AI 客户端的令牌用量。
服务日志按会话检索。当一个会话涉及多个文件时，diagnose_message 返回的关联证据可能包含同一会话中的其他文件。这是预期行为。
关联 ID 覆盖主要的消息处理路径。某些路径（例如某些计划重试工作进程）可能不携带关联 ID。

入门指南

工作流

EDI 交易伙伴管理控制台

端口

映射

系统 API

操作指南

脚本编写

软件许可和第三方版权

连接 AI 客户端

安全存储 Authtoken

在客户端配置文件中引用变量

Claude Desktop

使用 `--header-file` 引用令牌的替代方法

GitHub Copilot CLI

使用环境变量安全存储令牌

OpenAI Codex

使用环境变量安全存储令牌

关联 ID

可用工具

诊断工具

操作工具

示例提示

安全说明

本版本的已知限制

​连接 AI 客户端

​安全存储 Authtoken

​在客户端配置文件中引用变量

​Claude Desktop

​使用 --header-file 引用令牌的替代方法

​GitHub Copilot CLI

​使用环境变量安全存储令牌

​OpenAI Codex

​使用环境变量安全存储令牌

​关联 ID

​可用工具

​诊断工具

​操作工具

​示例提示

​安全说明

​本版本的已知限制

连接 AI 客户端

安全存储 Authtoken

在客户端配置文件中引用变量

Claude Desktop

使用 `--header-file` 引用令牌的替代方法

GitHub Copilot CLI

使用环境变量安全存储令牌

OpenAI Codex

使用环境变量安全存储令牌

关联 ID

可用工具

诊断工具

操作工具

示例提示

安全说明

本版本的已知限制