MCP 服务

MCP 让 Wuu 引擎使用本地进程或远程服务提供的工具。连接后，告诉 agent 服务名称和任务即可。Wuu 当前发现并调用工具，不提供资源或提示浏览器，也不支持 MCP 发起的额外用户输入交换。

在对话中使用插件

输入 @ 或点击 +，会打开同一个插件、技能和操作搜索面板。已连接的 MCP 服务，以及提供对话工具的活动插件可以被选择；主题和仅提供后台服务的包不会作为对话插件列出。不可用的连接提供连接或管理入口，面板也保留附件操作。

选择后，插件引用插入光标所在位置。可以继续输入、选择多个插件，或用退格/Delete 删除整项引用。草稿、排队消息和已发送消息保留插件与服务身份，包括授权标识。名称本身不是身份。可以用不同的 MCP 定义连接不同账号；不同项目使用同一规范定义时仍共享登录。

Wuu、Codex 和 Claude Code 支持插件引用。其他引擎适配器需要明确声明 conversation-plugins；不支持时，输入框会阻止选择和提交。运行中提交含插件引用的消息，会排队到下一轮。工具权限仍然有效。执行前会检查服务和授权是否仍与引用一致；更换登录后，需要重新选择服务。旧的运行中连接不能借用新登录。

连接管理会打开插件目录并保留草稿。完成授权后，返回对话选择已连接的服务。

添加服务

打开插件 → 添加 → 添加自定义 MCP 服务器，填写服务地址或本地命令及参数，也可以选择导入 JSON，粘贴 mcpServers 或 mcp_servers 对象。高级选项支持以 JSON 编辑请求头、环境变量、传输方式、OAuth 注册信息和工具时限。

定义保存在当前选中的配置提供方中，会立即应用。运行中的对话继续使用开始时的服务，新对话使用保存后的定义。编辑和删除会检查配置版本；其他窗口修改过配置时，请重新打开编辑器。导入会拒绝同名服务和不支持的连接字段；导入值按字面值保存，包括 ${VAR} 占位符。

也可以直接在用户配置的 mcp_servers 中添加定义，默认文件为 ~/.wuu/config.json。修改磁盘上的文件后请重启 Wuu。

以下片段配置一个本地服务和一个远程服务。请替换为实际可执行程序、脚本路径和 URL：

{
  "mcp_servers": {
    "project-tools": {
      "command": "node",
      "args": ["/absolute/path/mcp-server.js"],
      "env": { "PROJECT_ID": "demo" }
    },
    "docs": {
      "url": "https://mcp.example.com/mcp",
      "transport": "http"
    }
  }
}

对于 stdio，Wuu 直接使用 args 启动程序，不经过 shell。子进程继承进程环境，env 覆盖同名变量。服务必须把 stdout 留给协议消息，日志写到 stderr。

远程服务中，http 和 streamable-http 选择流式 HTTP，sse 选择旧式 SSE。省略 transport 时先探测 HTTP，端点不兼容才回退 SSE；网络不可达不会触发回退。明确指定传输方式时也不会回退。

流式 HTTP 的每条 POST 响应流归属于对应调用。调用完成或取消时，Wuu 会关闭该响应流。如果流在返回结果前结束，或发来无效、超出大小限制的消息，该调用会立即报错。由于工具可能已经产生实际效果，Wuu 不会因响应流中断而重放工具调用。其他调用和服务端通知流保持连接。如果 POST 响应误用其他调用的 ID，Wuu 会拒绝该响应，不会提前结束其他调用。服务端发起的反向请求使用独立的 ID 空间。

反向请求的回复使用独立的有界队列：每条连接最多同时发送 4 条回复、等待 32 条回复，从入队开始计算 5 秒期限。回复发送阻塞不会卡住工具结果或通知。来源 POST 调用完成或取消时，其等待中和发送中的回复都会取消；服务端取消通知按原始数字或字符串 ID 匹配请求。断开连接会取消回复任务并等待发送结束。回复失败或队列满时，只让其来源调用报错，不重放该调用。没有来源调用的反向请求洪泛塞满队列时，连接会因容量错误关闭；单条无来源回复发送失败会记入日志。已过期会话中的回复不会因服务器拒绝而重新发送到新会话。等待中的回复和认证重试也绑定收到请求时的会话；会话替换后，它们会失效，不会使用新会话 ID 发送。

远程 headers 使用字面值。原生 mcp_servers 不展开 ${VAR} 占位符。不要把秘密提交到配置中，也不要把占位符误当成凭据引用。enabled: false 保留定义，但启动时不连接。

工具执行时限

在服务定义中设置 tool_timeout_ms，可为较长的报告、导出或构建任务留出时间：

{
  "mcp_servers": {
    "docs": {
      "url": "https://mcp.example.com/mcp",
      "transport": "http",
      "tool_timeout_ms": 120000
    }
  }
}

该值为 1 到 3600000（一小时）之间的整数毫秒数。省略时保留默认的 30 秒。零、负数、小数、null、字符串和越界值均会被拒绝，不支持无限时限。每次调用都按实际经过的时间计时，包括等待响应头；进度通知不会延长时限。调用方取消、会话截止时间或 PTC 时限更早到达时，仍会提前结束等待。超时不能证明远端操作已停止或未产生副作用，Wuu 不会因为超时而重放工具调用。

此设置同时适用于原生调用和 PTC 嵌套调用，与连接及工具发现预算分开。已信任的项目 .mcp.json 服务和插件的 mcpServers / mcp_servers 声明使用相同字段。原生配置中只含 tool_timeout_ms（可同时含 enabled 或 tool_overrides）的同名条目会覆盖项目服务的时限，不替换其连接定义。插件服务使用限定名称，例如 plugin.my-plugin.docs。

修改磁盘上的设置后请重启。新加载的插件代际或重新连接会使用其已加载的时限；旧前台代际保留的调用继续使用旧时限。连接页面的“刷新”不会重新读取配置文件。

管理连接

打开插件管理独立 MCP 服务。插件自带的 MCP 显示在该插件详情页；需要 MCP 授权时，插件列表也会提示。禁用插件会禁用其服务。插件和项目定义保留原来的来源，不能当作独立定义直接编辑。

连接控件显示状态、工具数量和错误。MCP 服务列表中的条目，断开只结束当前连接，不删除定义或凭据。刷新使用已加载配置重新连接并发现工具。编辑会修改已保存的定义及启动偏好。移除会删除独立定义；项目中同名的定义可能重新生效。移除定义会保留已保存的 OAuth 凭据；如果也要退出登录，请先使用移除 OAuth 登录。

当插件自带服务和手动配置使用相同服务名称或地址时，列表会分别标注来源，不会合并授权；移除其中一条不会断开另一条。移除独立定义不需要等待无关对话结束。移除生效后，旧连接拒绝新的工具调用，已经接受的调用按原有超时正常收尾。其他正在运行的 Wuu 主机会在观察到保存的配置变化后应用移除。

修改磁盘上的定义后请重启 Wuu，刷新不会重新读取配置文件。旧的设置 MCP 深链仍保留兼容入口，主要管理入口为插件页。

模型可见的工具名类似 mcp_docs_search，不支持的字符和过长名称会规范化。大型或低频工具定义可能延迟展示，再通过工具搜索发现。当前工具集和权限策略仍可能限制工具可用性或执行。

会话与通知恢复

流式 HTTP 的可选 GET 通知流归属于已完成初始化的会话。会话过期时，即使多个调用同时收到 HTTP 404，也只共享一次恢复握手。新会话会关闭旧监听、清空旧续传位置，并在初始化完成后开始监听。旧会话中尚未消费的通知会被丢弃。HTTP 405 只关闭当前会话的 GET 监听。

使用 OAuth 时，GET 认证失败会刷新凭据并重试一次。后续 POST 成功刷新凭据后，也可以恢复监听，同时保留当前会话的续传位置。断开连接会取消监听和正在进行的恢复。恢复失败会显示为连接错误；解决错误后可使用刷新重新连接。

恢复不会因为工具响应流中断而重放调用，因为工具可能已经产生实际效果。Wuu 只在认证和会话恢复限制内，重试明确被 HTTP 401 或会话过期 HTTP 404 拒绝的请求。其他正在进行的 POST 调用仍只接收各自的最终响应。

项目 `.mcp.json`

Wuu 读取项目配置目录中的 Claude 风格 .mcp.json：

{
  "mcpServers": {
    "local-docs": {
      "command": "node",
      "args": ["/absolute/path/docs-server.js"],
      "env": { "API_TOKEN": "${API_TOKEN}" }
    }
  }
}

条目默认不加载。检查服务后，在不提交的 .wuu/settings.local.json 中批准其名称：

{
  "mcp_json": { "enabled": ["local-docs"] }
}

enable_all: true 启用除 disabled 外的全部条目，明确禁用的名称始终优先。只需要部分服务时，优先逐个填写名称。

与原生定义不同，.mcp.json 会在命令、参数、环境值、URL 和请求头中展开 ${VAR} 与 ${VAR:-default}。缺少变量且无默认值时保留原文，并发出警告。支持的类型为 stdio、http 和 sse。同名原生 mcp_servers 条目优先。

远程 OAuth

远程 URL 服务可以使用 OAuth 发现、PKCE、scope 和动态客户端注册。普通定义不必预先填写 oauth，遇到认证要求后，点击服务的 OAuth 登录。

桌面 Wuu 会打开授权页面并监听本机 HTTP 回调。授权完成后保存凭据并自动连接。未指定回调地址时使用可用端口；定义指定了固定本机回调地址时，使用该地址。回调会校验 state，并绑定发起登录的窗口和 app-server，切换工作区不会改变绑定。取消、关闭登录框、关闭窗口或超过十分钟期限时，会关闭监听并使待完成的授权失效。

浏览器客户端及使用非本机回调地址的服务支持手动完成：将回调地址或授权码粘贴到对话框。固定客户端需在服务端注册实际使用的回调地址。令牌进入 Wuu 凭据存储，而不是写回服务定义。

保存的凭据绑定到登录时使用的资源 URL。同名服务改用其他 URL 时，需要重新登录；路径或查询参数变化也属于不同资源。旧版本未记录资源 URL 的凭据同样需要重新登录。Wuu 会保留不匹配的凭据，直到你主动替换或移除；登录新资源会替换该服务名称下的凭据。

登出会使各 Wuu 进程中更早的登录尝试和正在执行的凭据刷新失效，迟到的响应不能恢复已移除的凭据。同名服务重新开始登录后，应完成最新的授权流程，旧流程不能覆盖新登录。浏览器授权或令牌交换失败不会清除已有凭据，登出后仍可主动重新登录。

桌面 MCP OAuth 凭据仍保存在 macOS Keychain 或 Linux Secret Service。Linux 需要运行中的会话 D-Bus，以及可用且已解锁的 Secret Service 密钥环，例如 GNOME Keyring。密钥环不可用或访问失败时，Wuu 会报告错误，不会回退到凭据文件。

仅所有者可访问的锁文件和凭据版本记录用于协调本机访问，与项目数据目录无关，不包含令牌或客户端密钥。请随本机 Wuu 状态一起保留这些版本记录。存储失败，或 Wuu 进程崩溃后仍在运行的后端命令，可能使凭据不可用并要求重新登录；过期版本或尚未提交的凭据不会被接受。共享凭据的所有 Wuu 进程都必须运行此版本或更新版本，才能保证上述行为。

携带 OAuth 凭据或配置请求头的请求不能跨源重定向，即协议、主机或端口不能变化。旧式 SSE 的消息端点必须与事件流同源，仍支持同源的不同路径和会话查询参数。

服务要求固定客户端、回调或 scope 时，在该服务下加入 oauth 对象：

{
  "redirect_uri": "http://127.0.0.1:8765/callback",
  "client_id": "your-client-id",
  "scopes": ["tools:read"]
}

请使用服务实际提供的注册值；服务也可能要求 client_secret。配置的资源请求头不会转发给跨源授权服务器。

工具元数据

服务定义可以通过 tool_overrides 修正工具的 read_only、concurrency_safe 或 capability 元数据，或附加 guidance 使用契约——当工具暴露给外部引擎时，宿主能力面会向引擎展示它。只有明确知道操作语义时才设置。把写操作误标为安全读取，可能绕过依赖这些声明的保护。

排查与信任

服务未出现时，检查配置拼写、重启 Wuu，并在使用 .mcp.json 时确认批准状态。本地连接错误应检查程序发现、依赖、环境和 stdout 内容；远程错误应检查 URL、传输方式、网络、请求头和 OAuth 要求。

已连接且有工具的服务，仍可能使用延迟展示；可以让 agent 搜索所需工具。服务描述和结果是外部内容，不是系统指令。本地 MCP 进程使用继承的环境运行受信任代码，远程服务则会收到调用参数。连接陌生服务前，请阅读安全模型。