本地 MCP 服务

这里讲的是 **你** 自己加的服务。没有可浏览的 MatchaCode 目录，没有托管 MCP 网关，也没有连接器的官方云。

添加本地（stdio）服务

通常第一个服务是本地进程。Matcha CLI 启动它，经 stdin/stdout 通信。

在项目目录里执行，或在任意位置添加用户级服务：

matcha mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir

-- 之后都是服务命令，因此 -y 这类标志会传给服务，而不是 matcha。

用可重复的 -e 给进程环境变量：

matcha mcp add postgres -e DATABASE_URL=postgres://localhost/mydb -- npx -y @modelcontextprotocol/server-postgres

默认范围是 **user**（~/.matcha/config.toml）。用 --scope project 写入当前目录的 ./.matcha/config.toml（可与团队共享）。

服务名只能包含字母、数字、连字符和下划线。

等价的 TOML：

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
enabled = true

指向你已有的远程服务

若第三方主机公布了 HTTP 或 SSE MCP 端点，你可以添加 **那个 URL**。这不是 MatchaCode 产品服务。

matcha mcp add --transport http sentry https://mcp.sentry.dev/mcp
matcha mcp add --transport sse linear https://mcp.linear.app/sse

重复 --header "Name: value" 做静态鉴权。提交进仓库的项目配置里，优先用 ${VAR}，不要粘贴密钥：

[mcp_servers.internal-tools]
url = "https://mcp.internal.example.com/mcp"
headers = { "Authorization" = "Bearer ${INTERNAL_MCP_TOKEN}" }

**你自己配置的**远程服务允许 OAuth。添加服务后，打开 /mcps，若主机要求登录，在该行按 i。令牌落到 ~/.matcha/mcp_credentials.json（Unix 上仅所有者可读写）。这个流程里没有 MatchaCode 账号。

列出、启用、停用、移除、诊断

matcha mcp list
matcha mcp list --json
matcha mcp enable filesystem
matcha mcp disable filesystem
matcha mcp remove filesystem
matcha mcp doctor
matcha mcp doctor filesystem

• list 显示用户级与项目级服务。项目行标 (project)；停用行标 (disabled)。
• remove 会搜两个范围。名字不存在，或两个范围都有同名时退出码为 1 — 用 --scope 指定。
• enable / disable 把你的个人开关写进用户级 ~/.matcha/config.toml。停用从不改写项目文件。启用可以清掉最近项目定义上粘住的 enabled = false。

在 TUI 里：`/mcps`

/mcps

这会打开扩展模态框的 **MCP Servers** 标签页。在 VS Code 系之外，也可以按 Ctrl+L 再切到该标签页。

MCP 工具带命名空间：服务 github 的工具 create_issue 变成 github__create_issue。助手用 search_tool 找到它们，再用 use_tool 调用。

项目 `.mcp.json` 与其他工具

Matcha CLI 也会 **读取** 它没有写出的 MCP 配置：

名字冲突时，更高来源胜出：config.toml > Claude > Cursor > .mcp.json。用 [compat.cursor] mcps = false 或 MATCHA_CURSOR_MCPS_ENABLED=false 关掉某家扫描（Claude 对应项同理）。

matcha inspect 列出每个已加载服务，并标上厂商来源（[cursor]、[claude]）。

项目 .matcha/config.toml 从 cwd 向上走到 git 根。最深的文件胜出。同名的项目服务会 **整份替换** 用户服务（字段不合并）。

目前没有什么

• **MCP 市场** — 没有可从中安装的目录。
• **托管 MCP 网关** — 没有 managed_gateway:… 连接器。它们不会出现在 /mcps 和 matcha mcp enable / disable 里。

若服务启动不了，先自己跑它的命令，再看 ~/.matcha/logs/mcp/<server>.stderr.log。matcha mcp doctor 和 matcha inspect 显示配置了什么、连上了什么。

你应该看到