MCP 服务器

Mework 是 MCP 客户端：在 mcp.json 里声明服务器，为每个对话选择要用哪些，它们的工具就成了模型可以调用的工具。Mework 支持 stdio 和 Streamable HTTP 两种服务器，只使用服务器的工具，不使用它的提示词（prompts）和资源（resources）。

mcp.json 放在哪里

对话可以从全局服务器和它所有工作区的服务器里挑选。服务器属于某台机器，而不属于某个工作区：

• 工作区的服务器在这个工作区所在的机器上运行。工作区在 WSL 或 SSH 机器上时，Mework 在那台机器上读取它的 mcp.json，在那里启动它的 stdio 服务器，并通过那台机器的网络连接它的 HTTP 服务器。这样的服务器可以用于对话里同一台机器上任何一个工作区的工作。
• 全局服务器从本机启动和连接。

对话的工作区不全是本机上的同一个文件夹时，系统提示词会为每个已选服务器告诉模型：它在哪台机器上运行，对话的哪些工作区在那台机器上（或者一个也没有）。

对话在某个工作区的隔离工作树里工作时，这个工作区的 mcp.json 仍从它自己的文件夹读取。临时项目的临时文件夹没有 .mework；那里的对话能用全局服务器，以及它附加的工作区的服务器。

文件格式

格式与 Claude Code 的 .mcp.json 相同：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    },
    "docs": {
      "type": "http",
      "url": "https://docs.example.com/mcp",
      "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" }
    }
  }
}

• mcpServers 下的每个键是一个服务器名，只能由 ASCII 字母、数字、- 和 _ 组成。
• 文件不是合法 JSON，或者服务器没有写在 mcpServers 下时，整份文件都会被忽略。文件开头带 UTF-8 字节顺序标记（BOM）没有关系。
• 没通过检查的条目标为 不可用，原因写在悬停提示里；文件里的其他条目照常可用。对话选着不可用的服务器时，每次运行都会失败。

键

带 oauth 或 headersHelper 的条目不可用：Mework 不执行登录流程，也不运行生成请求头的脚本，请把令牌直接写进 headers。Mework 不认识的键一律忽略，包括其他客户端的 "disabled": true、autoApprove、alwaysAllow。要停用某个服务器，取消勾选即可。

在工作区里工作的服务器

带 "workspace": true 的全局 stdio 服务器跟随对话在本机上的工作区：

• 本机上有两个或更多这样的工作区时，服务器的每个工具都会多出一个 workspace 参数：整数，取这些工作区之一的编号，默认第一个。每次调用都交给在那个工作区文件夹里启动的一份服务器实例，取代 cwd；调用到达服务器之前，Mework 会去掉这个参数。
• 只有一个时，服务器像其他全局服务器一样在那里启动，工具也不多出参数。
• 工具自己的 schema 里已经有 workspace 属性时，这个工具的 schema 保持原样，调用一律交给第一个工作区。

值里的环境变量

command、args、env 的值、url、headers 的值里的 ${VAR} 和 ${VAR:-默认值} 会被替换，cwd 里的不会；变量未设置又没有默认值时，条目不可用。变量取自 Mework 自身的环境，macOS 上包括登录 shell 导出的变量（~/.zprofile、~/.zshrc）；改了变量后需要重启 Mework。WSL 或 SSH 工作区的 mcp.json 里，变量取自那台机器的环境和工作区的 环境变量（见工作区）。

服务器的环境

stdio 服务器不继承 Mework 的环境。它从空环境开始，依次得到：

1. PATH、PATHEXT、SystemRoot、WINDIR、COMSPEC、TEMP、TMP、TMPDIR、HOME、USERPROFILE、APPDATA、LOCALAPPDATA、PROGRAMDATA、ProgramFiles、ProgramFiles(x86)、XDG_CACHE_HOME、XDG_CONFIG_HOME；macOS 上还有 USER、LOGNAME、SHELL、TERM、LANG、LC_ALL、LC_CTYPE、SSH_AUTH_SOCK，以及大小写两种写法的 http_proxy、https_proxy、all_proxy、no_proxy。
2. envPassthrough 里列出的变量。
3. env。

WSL 或 SSH 工作区里声明的服务器，环境取自那台机器而不是本机，另加工作区的 环境变量。

envPassthrough 拒绝以 MEWORK_、ANTHROPIC_、OPENAI_、CLAUDE_、CODEX_、AWS_、AZURE_、GOOGLE_、GEMINI_、DEEPSEEK_ 开头的名字，以免凭据被顺手转交出去。确实要给服务器其中某个变量时，写在 env 里，例如 "env": { "AWS_PROFILE": "${AWS_PROFILE}" }。

为对话选择服务器

1. 打开 更多选项 → 对话设置 → MCP（见对话设置）。
2. 勾选这个对话要用的服务器。

保存 mcp.json 后，列表很快会自动刷新；按 重新扫描 可以立即刷新，运行时总是按磁盘上的文件为准。列表先是 全局 一节，再按工作区各分一节（见对话设置）。每节标题上的文件夹按钮（打开全局配置目录 或 打开 {path} 的配置目录）会显示这一层的 mcp.json，需要时先创建 .mework 文件夹。对 WSL 或 SSH 工作区，它会在文件面板里打开那台机器上的这个文件夹。

测试连接（可用行上的插头图标）会启动服务器一次，列出它的工具。失败时，这一行的悬停提示里有错误信息和服务器写到 stderr 的最后五行。

• 模型的提示缓存未过期时，改动服务器选择会标成橙色，并询问一次。
• 模型没有 中途追加工具 属性时（见模型属性），第一次请求之后选择就被冻结（灰色），但 悬空 的行仍然可以取消勾选。
• 点垃圾桶按钮，等它变成 确认 后再点一次，只会从所在的 mcp.json 里删掉这个服务器的条目。选过它的对话会显示 悬空；取消勾选之前，每次运行都会失败，并写明是哪个服务器。
• 内置的 mework 预设不选任何服务器。

每一轮发生什么

每一轮开始时，Mework 连接每个已选服务器，获取它的工具列表。如果 mcp.json 里的某个服务器连不上，或者因为超过限制被略过，这一轮会显示一条提示，写明是哪个服务器、什么原因；其他服务器的工具照常提供。已选的服务器如果已不在 mcp.json 里，就显示为 悬空，运行会直接失败。

每个对话有自己的服务器进程或连接，所以三个对话用同一个 stdio 服务器时，会运行三份进程。空闲 30 分钟后它会关闭；条目改动后，下一轮会重新建立。

超过 64 KiB 的调用结果会被整体拒绝，而不是截断；图片和 base64 数据很容易超过这个大小。结果里 isError: true 表示调用失败。

工具名

模型看到的工具名形如 mcp__<服务器>_<哈希>__<工具>__<哈希>：服务器名缩成最多 12 个小写字母、数字和 _，工具名缩成最多 18 个，两个哈希各是 10 位十六进制数，改服务器名或移动它所在的 mcp.json 后都会变。

要在钩子里匹配某个服务器的全部工具，用 ^mcp__<缩短后的服务器名>_。

工具发现

MCP 页底部的 工具发现 开关决定工具怎样声明：

• 全部声明（关）：每次请求都带上所有已选服务器的工具 schema。
• 按需取回（开）：不发送任何 MCP schema。模型拿到一份工具名清单，用 tool_search 取回需要的工具，从下一步起可以调用。

内置的 mework 预设会打开工具发现。它要求模型有 中途追加工具 属性，没有时开关不可用。提示缓存未过期时，切换这个开关会标成橙色。子代理沿用父对话的设置。

审批

在 手动 和 允许编辑 两个安全级别下，每次 MCP 调用都会询问。在 完全访问 下不弹审批卡，下面最后一条所说的工具除外。

• MCP 审批卡总是标为高风险，也从不提供 总是允许。
• PreToolUse 或 PermissionRequest 钩子可以代你批准调用。
• 有些工具每次调用都要询问，即使在完全访问下也一样，任何钩子都跳不过：服务器用 _meta["anthropic/requiresUserInteraction"] 标记的工具，以及你写进 disabledAutoApproveTools 的工具。

限制

排查问题

列表里没有这个服务器。 确认文件是合法 JSON，服务器写在 mcpServers 下。WSL 或 SSH 工作区的 mcp.json 要放在那台机器上。旧的 .naiword/mcp.json 只在同一层级没有 .mework/mcp.json 时才会被读取；把它移过来后，需要重新勾选。

工具始终不出现。 这一轮的提示会写明原因，测试连接 可以看到服务器写到 stderr 的内容。服务器只能看到服务器的环境里列出的变量。如果服务器超过了 schema 上限，用 disabledTools 排除它的部分工具。