跳到主要内容

MCP 服务

XTerminal 提供本地 MCP（Model Context Protocol）服务，让 Codex、Claude Code 等客户端通过 Streamable HTTP 使用 XTerminal 中经过授权的连接、远程文件和工作区能力。

MCP 会把外部客户端请求带回 XTerminal。SSH 命令、SFTP 文件操作和工作区写入是否需要确认，分别由 XTerminal 中的访问范围、执行策略和客户端权限控制。

MCP 服务与工具配置

截图展示的是当前设置页的“工具”标签：服务处于停止状态，监听地址为本机回环地址，工具按工作区、SSH、远程文件和文件传输分组显示。背景连接和数值属于本地演示环境。

注意

MCP 客户端可以操作远程服务器或本地文件。首次配置时建议保留“每次确认”、只暴露指定服务器和指定本地目录，并且只给可信客户端签发令牌。

能力范围​

MCP 设置中的 工具 标签按功能分组管理。当前工具包括：

分组能力
工作区浏览连接、分组、快速命令、笔记和分类；创建或修改这些工作区数据
SSH 操作列出已暴露的 SSH 服务器，执行普通 SSH 命令或 sudo 命令
远程文件列出目录、检查路径、读取远程文本、写入远程文本
文件传输上传、下载、查看传输状态和取消传输

工具开关对所有 MCP 客户端生效。至少要保留一个工具；关闭工具后，已连接的客户端需要重新连接才能刷新工具定义。

MCP 不会通过工具返回已保存的私钥或密码。连接保存操作只有在用户明确提供密码时才会接受密码字段，其他情况下不会让客户端读取现有凭据。

开启服务​

  1. 打开 设置 > AI 助手 > MCP 服务。
  2. 打开 启用 MCP 服务。
  3. 检查服务地址和监听端口。
  4. 在 工具、访问范围 和 执行策略 中完成限制。
  5. 在 客户端 标签中为 Codex 或 Claude Code 创建访问令牌。

默认地址是 127.0.0.1，默认端口是 12335，服务端点格式为：

http://127.0.0.1:12335/mcp

端口必须在 1024 到 65535 之间。修改端口后点击 应用；如果端口已经被其他程序占用，MCP 会启动失败，不会自动切换到另一个端口。

监听地址​

默认只监听本机回环地址，适合 Codex 和 Claude Code 与 XTerminal 在同一台设备上的场景。

如果需要让 WSL 或其他受控环境访问，可以将地址改为 0.0.0.0 或当前环境可达的地址。这样会扩大服务暴露面，必须同时限制客户端令牌、SSH 服务器和本地目录，并由网络层阻止不可信来源访问端口。

监听地址不是远程服务地址。MCP 客户端连接的是运行 XTerminal 的设备，远程命令仍然通过 XTerminal 中配置的 SSH 连接执行。

访问范围​

SSH 服务器​

在 访问范围 > 允许访问的 SSH 服务器 中选择：

选项行为
全部服务器暴露当前 XTerminal 中全部 SSH 连接
指定服务器只暴露选中的 SSH 连接

建议使用 指定服务器。MCP 客户端必须先使用 xterminal_ssh_list_servers 获取已暴露的服务器，再使用返回的服务器 ID 发起命令或文件操作。

本地目录​

在 访问范围 > 允许访问的本地目录 中选择：

选项行为
全部本地目录允许上传源文件和下载目标位于任意本地目录
指定目录只允许位于所选目录内的本地路径

指定目录会按实际路径边界检查，不能通过 .. 或符号链接绕过允许范围。上传源文件和下载目标都受这项设置限制。

MCP 访问范围

访问范围页同时控制 SSH 服务器和本地目录，未选择的范围不会因为工具开关开启而自动暴露。

执行策略​

SSH 与 SFTP 操作​

命令执行策略控制普通 SSH 命令和远程文件操作：

选项行为
每次确认每个操作都在 XTerminal 中显示目标、命令或路径，确认后才执行
直接执行跳过 XTerminal 确认并立即执行

“直接执行”只适用于明确可信的客户端。它不会扩大服务器或本地目录访问范围，但会取消人工确认这一层保护。

确认窗口会显示请求客户端、目标服务器、操作类型、命令、工作目录和文件路径。覆盖文件时会显示覆盖警告。请求超过等待时间或窗口关闭后会被拒绝。

sudo 操作​

sudo 执行策略独立于普通命令：

选项行为
禁用不允许 MCP 使用 sudo 工具
每次确认每次 sudo 请求都需要确认
直接执行允许符合权限条件的请求跳过确认

启用 sudo 后还要选择凭据方式：

  • 每次输入 sudo 密码：在确认窗口中临时输入，仅用于本次执行。
  • 复用 SSH 登录密码：明确允许 XTerminal 使用已保存的 SSH 登录密码完成 sudo。

MCP 客户端不应在命令参数中传递 sudo 密码。执行 xterminal_ssh_sudo_exec 时也不需要在命令前手动写 sudo，XTerminal 会在授权后处理提权。

令牌还必须单独开启 允许 sudo，因此“全局 sudo 策略”和“客户端令牌权限”都允许时，客户端才可能使用 sudo。

MCP 执行策略

工作区管理​

工作区管理策略控制 MCP 对连接、分组、快速命令和笔记的读取与写入：

选项行为
禁用不允许 MCP 读取或修改工作区
写入时确认读取目录或目录信息按策略执行，创建和修改数据前显示预览并确认
直接保存跳过工作区写入确认

客户端令牌还必须开启 允许工作区管理。工作区确认窗口会按“连接设置”“笔记分类”“保存字段”分组展示内容，并隐藏密码值；较长的笔记内容会截断预览，只显示内容长度。

云端保存仍然受登录状态和 Pro 权限检查，不会因为启用 MCP 而绕过账号限制。

配置客户端​

创建令牌​

  1. 确认 MCP 状态为 运行中。
  2. 打开 客户端 标签。
  3. 点击 添加 Codex 或 添加 Claude Code。
  4. 复制弹窗中生成的配置或命令。
  5. 将配置保存到对应客户端后，点击 我已保存配置。

创建入口只显示客户端类型和权限管理按钮，不会在页面中再次显示完整令牌；下面的裁剪图没有包含任何令牌值。

MCP 客户端入口

令牌只在创建弹窗中显示一次。令牌以 Bearer 令牌形式发送，不能提交到代码仓库、聊天记录或截图中。客户端列表只保存令牌摘要和权限状态，不显示完整令牌。

Codex​

界面会生成类似下面的配置。实际端点和令牌请使用弹窗内容：

[mcp_servers.xterminal]
url = "http://127.0.0.1:12335/mcp"
http_headers = { Authorization = "Bearer <MCP_TOKEN>" }
default_tools_approval_mode = "prompt"
tool_timeout_sec = 120

Claude Code​

界面会生成类似下面的命令：

claude mcp add --transport http --scope user --header "Authorization: Bearer <MCP_TOKEN>" xterminal http://127.0.0.1:12335/mcp

不要手动把真实令牌替换到文档、脚本示例或公共终端记录中。配置完成后，如果在 XTerminal 中关闭了某个工具，重新连接客户端让工具列表更新。

令牌权限​

客户端列表中可以分别切换：

  • 允许 sudo：允许该令牌使用 sudo 工具，但仍受 sudo 执行策略和目标服务器范围限制。
  • 允许工作区管理：允许该令牌使用工作区读取或写入工具，但仍受工作区管理策略限制。

撤销令牌会立即终止该客户端后续的 MCP 请求和传输任务。发现令牌泄露时，应先撤销令牌，再重新创建客户端配置。

常见操作​

远程命令​

推荐流程：

  1. 调用 xterminal_ssh_list_servers 查找目标服务器。
  2. 使用返回的 serverId 调用 xterminal_ssh_exec。
  3. 检查返回的退出码、标准输出、标准错误和执行耗时。

命令是非交互式执行，默认超时为 60 秒，单次最多 600 秒。需要交互式终端、密码输入或持续运行的程序时，应回到 XTerminal 的 SSH 终端执行。

远程文件​

SFTP 工具支持列目录、检查元数据、读取或写入文本文件，也支持上传、下载、查看传输状态和取消传输。大文件或长时间传输应通过传输状态工具跟踪，不要重复提交同一任务。

工作区数据​

使用工作区工具时，先浏览目录获得已有资源和 ID，再创建或更新目标对象。更新操作需要提供已有对象 ID；创建操作省略 ID 后会返回新 ID。

MCP 返回的工作区数据会过滤保存的密码、私钥、私钥密码和 SSH 代理凭据。

故障排查​

客户端无法连接​

  • 检查 MCP 状态是否为 运行中。
  • 检查客户端端点、端口和 /mcp 路径是否一致。
  • 检查令牌是否完整、是否已经撤销。
  • 修改工具配置后，重启或重新连接客户端。
  • 如果修改了监听地址，确认客户端所在环境可以访问该地址。

找不到 SSH 服务器​

确认连接中心中存在 SSH 连接，并在 MCP 的 允许访问的 SSH 服务器 中暴露了目标连接。使用“指定服务器”时，新增连接不会自动获得访问权限。

请求一直等待或被拒绝​

确认 XTerminal 窗口仍在运行且没有关闭确认弹窗。普通命令、SFTP 操作和工作区写入分别受不同策略控制；还要检查对应客户端令牌是否开启了 sudo 或工作区管理权限。

端口启动失败​

端口冲突、监听地址格式无效或端口小于 1024 都会导致启动失败。更换未占用的端口后点击 应用，再检查状态标签和错误提示。

相关文档​