本机 MCP 服务

面向 v0.4.0 起的实现；较早的 v0.3.1 不具备本文全部接口。各平台实测边界见 测试说明。 MCP 是外部工具与 Vex 沟通的协议，不是内置 AI，也不是云同步。

从哪里开始

可以做什么

客户端可以读取当前文档、选区和大纲，在授权目录内列出或读取 Markdown 文件，查找内容，经确认后修改正文和章节，并控制部分视图设置。导图来自文档标题树，修改章节会同步改变正文和导图。

目前只提供 Tools，不声明 Resources、Prompts、订阅或远程服务能力。导出、打印、删除磁盘文件、安装更新、执行命令和任意偏好读写没有开放给 MCP。接口齐全的判断依据是已发布的工具范围，不是把软件所有按钮都暴露出去。

Windows、macOS、Linux 桌面允许启用；Android、iOS 不启动常驻 MCP 服务。macOS / Linux 的凭据系统与原生文件授权仍需要对应系统验收；不把 Windows 测试等同于跨平台通过。

开启与连接

1. 在 Vex 的「偏好设置 → MCP」中设置访问范围，建议先保留「当前文档」和「修改前确认」。
2. 启用服务。默认地址为 http://127.0.0.1:17891/mcp/，更改端口后以界面实际地址为准。
3. 点击「测试连接」确认应用内自测成功，再复制客户端配置。
4. 在支持 Streamable HTTP 和自定义请求头 的客户端中添加服务器，填写 URL 和 Authorization: Bearer <令牌>。
5. 先调用 vex_get_capabilities、vex_get_document，使用专门的副本文档试验修改。

通用配置示意如下。不同客户端的配置字段可能不同；只支持 stdio 的客户端不能直接使用这段配置。

{
  "mcpServers": {
    "vex": {
      "url": "http://127.0.0.1:17891/mcp/",
      "headers": {
        "Authorization": "Bearer <从 Vex 复制的访问令牌>"
      }
    }
  }
}

sequenceDiagram
  participant U as 用户
  participant C as MCP 客户端
  participant V as 本机 Vex
  U->>V: 开启服务并设定范围
  C->>V: initialize + Bearer 令牌
  V-->>C: 协议版本与 tools 能力
  C->>V: tools/list
  V-->>C: 工具及参数定义
  C->>V: vex_get_document
  V-->>C: 文档、document_id、revision
  C->>V: vex_apply_edits
  V->>U: 请求修改确认
  U->>V: 允许
  V->>V: 重查范围、文档和版本
  V-->>C: 操作结果与新 revision

权限与数据安全

Windows 当前插件使用 DPAPI 保护应用数据目录中的加密凭据，macOS 使用 Keychain，Linux 依赖 Secret Service。Linux 桌面需要可用且已解锁的密钥服务；构建需要 libsecret-1-dev。没有系统凭据环境时不应绕过失败改用明文文件。

服务只监听 IPv4 回环地址，检查 Host、拒绝带 Origin 的请求，没有浏览器 CORS 开放、OAuth 登录、TLS 或公网部署模式。不需要映射端口或放行公网防火墙。浏览器版 Inspector 应通过它自己的本地代理连接，不要为直接网页访问放开 Origin 检查。

本机并不等于绝对安全。相同系统账户下的恶意程序仍可能获取凭据或访问文件；客户端拿到正文后，也可能按它自己的设置发送给外部模型。请分别检查客户端的数据政策和权限。

不要把真实令牌、含令牌的客户端配置、剪贴板截图或完整用户配置目录上传到 GitHub。关闭服务不会清除系统安全存储中的令牌；疑似泄露时关闭服务、重新生成令牌再连接，旧令牌在新配置生效后失效。换电脑重新生成令牌，不直接复制系统加密凭据文件。

停止与排错

在 MCP 设置中关闭服务或退出 Vex 即停止监听；已经在等待用户确认的请求会被拒绝。这里没有后台独立守护进程。

更多安全说明：安全政策。