接入 MCP 服务器

Agent 在启动时会连接 Model Context Protocol 服务器。它们的工具进入与内置工具相同的 ToolRegistry，并默认带有 defer_loading: true（schema 只在模型调用 tool_search 时才被取回）。

两个文件位置

服务器配置会从两个地方读取并合并：

用户全局：<dataDir>/mcp/servers.json，默认 ~/.minara/mcp/servers.json。可通过 MINARA_DATA_DIR 覆盖目录。放个人凭据和你希望在每个仓库都能用的服务器。当 mcp/servers.json 不存在时，旧路径 <dataDir>/mcp.json 仍会被读取，已有配置照常工作。
项目本地：<repo>/.minara/mcp/servers.json。从 cwd 向上查找最近的 .minara/ 目录（与 .git/ 同级）即可定位。用来为单个仓库钉死开发 URL 或租户专用 token。旧路径 <repo>/.minara/mcp.json 是同样的回退。

id 冲突时项目级条目胜出，所以仓库可以覆盖全局已有服务器的 authTokenEnv 或 url。

两个文件共用同一种结构：

{
  "mcpServers": {
    "slack": {
      "url": "https://mcp.example.com/slack/",
      "authTokenEnv": "SLACK_MCP_TOKEN",
      "headers": { "X-Tenant": "acme" }
    },
    "etherscan": {
      "url": "https://mcp.example.com/etherscan/",
      "timeoutMs": 60000,
      "subagent": {
        "systemPrompt": "你专门回答 EVM 区块浏览器查询。",
        "maxSteps": 10
      }
    }
  }
}

JSON 的键即为服务器 id（用作 mcp_<id>_* 工具名前缀）。如果需要同一服务器以不同别名注册多次，可在条目中显式写 "id" 字段覆盖键。

字段

字段	必填	说明
`url`	是	Streamable-HTTP 的 MCP 端点。不支持仅 SSE 的端点。
`authTokenEnv`	否	持有 bearer token 的环境变量名。连接时从环境解析，作为 `Authorization: Bearer <token>` 发送。优先于 `authToken`，secret 不落盘。
`authToken`	否	bearer token 字面值。存在时会被读取，但写这个文件的工具（`minara mcp add`、chat 内安装路径）会拒绝 inline token 并要求 `authTokenEnv`。可信主机上手写的文件仍可用它。
`headers`	否	额外 HTTP 头，合并到每次请求里。secret 类头值（`Authorization`、`X-Api-Key`）必须引用环境变量，例如 `"Authorization": "Bearer ${SLACK_MCP_TOKEN}"`。
`timeoutMs`	否	单次调用超时。默认 30000。
`label`	否	日志中显示的名字，默认为 id。
`maxTools`	否	单服务器注册工具数硬上限，默认 64。
`include`	否	远程工具名白名单，未列出的全部丢弃。
`subagent`	否	设置后，该服务器的工具被包成单个 `mcp_<id>_query`，由内部 agent 循环驱动。对工具众多的服务器，用持久人格 + 步数预算保持主循环简洁。

非法条目（缺 url、类型错）会被记录后跳过：：单条坏数据不会阻断其余服务器接入。

优先级

MCP_SERVERS 环境变量 ：：服务器配置 JSON 数组，会短路两个文件位置。测试和容器部署用，通常由 secrets manager 直接注入。
合并后的服务器配置 ：：全局 <dataDir>/mcp/servers.json 与项目本地 <repo>/.minara/mcp/servers.json 合并（各自回退到同级旧路径 mcp.json）。id 冲突时项目级覆盖全局；id 不同的条目取并集。
v1 单服务器 URL 环境变量 ：： MCP_EVM_RPC_URL、MCP_ETHERSCAN_URL、 MCP_SOLSCAN_URL、MCP_GOPLUS_URL，各自独立开关，仅在前两层都为空时才生效。

就算磁盘上有配置文件，MCP_SERVERS=… 也总会短路文件，保留可复现性。

安全

secret 不要写进配置文件。用 authTokenEnv（环境变量名）表达鉴权， token 在连接时从环境解析。写这个文件的工具（minara mcp add 和 chat 内安装路径）会强制这一点。它拒绝 inline authToken，也拒绝持有字面值的 secret 头，token 不会经由 Agent 落盘。

可信主机上手写的文件仍可携带字面值 authToken，loader 会读取它。共享主机上请优先用 authTokenEnv。如果你必须存字面值 token：

chmod 600 ~/.minara/mcp/servers.json 与 chmod 600 <repo>/.minara/mcp/servers.json。
或者通过 MCP_SERVERS 从 secrets manager（Vault、AWS Secrets Manager、doppler 等）注入，让配置文件留空。
项目本地文件如不希望与仓库协作者共享 token，记得把 .minara/ 加进 .gitignore。

可观测性

启动日志的 module: "app"、action: mcp_initialized 行会列出已连接的服务器和工具数。单服务器失败以 mcp_server_connect_failed 上报。

REPL 中 pnpm dev -- status（或对应 HTTP gateway 端点）会汇报实时 MCP 状态数组。

两个文件位置

字段

优先级

安全

可观测性

本页目录