feat(mcp): add MCP

docs/api.md

@@ -290,6 +290,42 @@ Additional notes:
 - `field_mask` limits which fields are overwritten during replacement
 - `agent_profile.api_key` is write-only and will be redacted in reads
 
+OpenClaw, PicoClaw, and Codex CLI agents can configure MCP servers through the
+top-level `mcp_config` field. The API accepts the same `mcpServers` object for
+all supported runtimes and each runtime adapter renders it into its native
+configuration format:
+
+```json
+{
+  "name": "alice",
+  "runtime_kind": "openclaw_sandbox",
+  "mcp_config": {
+    "mcpServers": {
+      "workspace-filesystem": {
+        "command": "npx",
+        "args": [
+          "-y",
+          "@modelcontextprotocol/server-filesystem",
+          "/home/node/.openclaw/workspace"
+        ]
+      }
+    }
+  },
+  "profile": "api.gpt-5.4"
+}
+```
+
+Runtime adapters map this shared input as follows:
+
+- OpenClaw: `mcp_config.mcpServers` -> `openclaw.json` `mcp.servers`
+- PicoClaw: `mcp_config.mcpServers` -> PicoClaw config `tools.mcp.servers`
+- Codex CLI: `mcp_config.mcpServers` -> managed `[mcp_servers."<name>"]` blocks in the isolated Codex home `config.toml`
+
+MCP commands run inside the target runtime environment, so filesystem server
+directory arguments must be paths visible to that runtime. Existing clients
+that still send legacy `runtime_options.mcp` are normalized into `mcp_config`;
+new clients should use `mcp_config`.
+
 ### `GET /api/v1/agents/{id}`
 
 Gets a single agent.
@@ -306,6 +342,7 @@ Supported fields:
 - `description`
 - `image`
 - `runtime_options`
+- `mcp_config`
 - `agent_profile`
 
 Example request body:
@@ -322,6 +359,9 @@ Example request body:
 Notes:
 
 - Omitted fields are left unchanged
+- `runtime_options` uses whole-object replacement when submitted
+- `mcp_config` uses whole-object replacement when submitted; send `null` to clear CSGClaw-managed MCP config
+- Updating MCP config on OpenClaw, PicoClaw, or Codex CLI agents may recreate that agent runtime so the native config takes effect
 - If `agent_profile.api_key` is sent empty, the server keeps the existing key
 - If `agent_profile.env` changes, `env_restart_required` may become `true` in the response
 

docs/api.zh.md

@@ -287,6 +287,36 @@ Participant 是 channel-scoped identity，用于房间、消息、mention、通
 - `field_mask` 用于替换时只覆盖指定字段
 - `agent_profile.api_key` 只在写入时使用，读取时会被脱敏
 
+OpenClaw、PicoClaw 和 Codex CLI agent 可通过顶层 `mcp_config` 字段配置 MCP server。CSGClaw API 对所有已支持 runtime 接收一致的 `mcpServers` 输入，再由各 runtime adapter 渲染为对应的原生配置：
+
+```json
+{
+  "name": "alice",
+  "runtime_kind": "openclaw_sandbox",
+  "mcp_config": {
+    "mcpServers": {
+      "workspace-filesystem": {
+        "command": "npx",
+        "args": [
+          "-y",
+          "@modelcontextprotocol/server-filesystem",
+          "/home/node/.openclaw/workspace"
+        ]
+      }
+    }
+  },
+  "profile": "api.gpt-5.4"
+}
+```
+
+各 runtime adapter 的映射关系：
+
+- OpenClaw：`mcp_config.mcpServers` -> `openclaw.json` 的 `mcp.servers`
+- PicoClaw：`mcp_config.mcpServers` -> PicoClaw 配置的 `tools.mcp.servers`
+- Codex CLI：`mcp_config.mcpServers` -> 隔离 Codex home `config.toml` 中由 CSGClaw 管理的 `[mcp_servers."<name>"]` 块
+
+注意：MCP command 在目标 runtime 环境内执行，filesystem server 的目录参数也必须是该 runtime 可见路径。旧客户端继续提交 `runtime_options.mcp` 时会被服务端迁移为 `mcp_config`；新客户端应直接使用 `mcp_config`。
+
 ### `GET /api/v1/agents/{id}`
 
 获取单个 agent。
@@ -303,6 +333,7 @@ Participant 是 channel-scoped identity，用于房间、消息、mention、通
 - `description`
 - `image`
 - `runtime_options`
+- `mcp_config`
 - `agent_profile`
 
 请求体示例：
@@ -319,6 +350,9 @@ Participant 是 channel-scoped identity，用于房间、消息、mention、通
 说明：
 
 - 省略的字段不会修改
+- `runtime_options` 一旦提交就是整体替换
+- `mcp_config` 一旦提交就是整体替换；传 `null` 可清除 CSGClaw 托管的 MCP 配置
+- OpenClaw、PicoClaw 或 Codex CLI agent 的 MCP 配置变更可能触发该 agent runtime recreate，使原生配置生效
 - `agent_profile.api_key` 如果传空，服务端会保留原有密钥
 - 如果 `agent_profile.env` 发生变化，响应中的 `env_restart_required` 可能为 `true`