MINARA接入 MCP 服務器
通過 `mcp/servers.json` 把外部 MCP 服務器接進 Agent
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 狀態數組。