From 39726573aac2b600cb3f2e4f36abd2916c053962 Mon Sep 17 00:00:00 2001
From: "Zhengxu (Joshua) Jin" <33077399+Jinzhengxu@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:15:21 +0800
Subject: [PATCH] docs: fix the documented skill and MCP enable/disable
 endpoints (#5778)

The docs site pointed at POST /api/extensions/{skills,mcp}/{name}/enable
and /disable, and backend/docs/API.md at POST /api/skills/{name}/enable
and /disable. None of these routes exist. The gateway toggles a skill
with PUT /api/skills/{skill_name} and an MCP server with
PATCH /api/mcp/config, both admin-only, which is also what the
frontend calls.
---
 backend/docs/API.md                        | 32 ++++++++++++----------
 frontend/src/content/en/harness/mcp.mdx    |  2 +-
 frontend/src/content/en/harness/skills.mdx |  2 +-
 frontend/src/content/zh/harness/mcp.mdx    |  2 +-
 frontend/src/content/zh/harness/skills.mdx |  2 +-
 5 files changed, 21 insertions(+), 19 deletions(-)

diff --git a/backend/docs/API.md b/backend/docs/API.md
index 12155070fa..d1c034e553 100644
--- a/backend/docs/API.md
+++ b/backend/docs/API.md
@@ -825,31 +825,31 @@ GET /api/skills/{skill_name}
 }
 ```
 
-#### Enable Skill
+#### Enable or Disable Skill
 
 ```http
-POST /api/skills/{skill_name}/enable
+PUT /api/skills/{skill_name}
+Content-Type: application/json
 ```
 
-**Response:**
+Requires an authenticated admin session.
+
+**Request Body:**
 ```json
 {
-  "success": true,
-  "message": "Skill 'pdf-processing' enabled"
+  "enabled": false
 }
 ```
 
-#### Disable Skill
-
-```http
-POST /api/skills/{skill_name}/disable
-```
-
-**Response:**
+**Response:** the updated skill. An unknown `skill_name` returns `404`.
 ```json
 {
-  "success": true,
-  "message": "Skill 'pdf-processing' disabled"
+  "name": "pdf-processing",
+  "description": "Handle PDF documents efficiently",
+  "license": "MIT",
+  "category": "public",
+  "enabled": false,
+  "editable": false
 }
 ```
 
@@ -1476,7 +1476,9 @@ curl -X POST http://localhost:2026/api/threads/abc123/uploads \
   -F "files=@document.pdf"
 
 # Enable skill
-curl -X POST http://localhost:2026/api/skills/pdf-processing/enable
+curl -X PUT http://localhost:2026/api/skills/pdf-processing \
+  -H "Content-Type: application/json" \
+  -d '{"enabled": true}'
 
 # Stateless stream — no thread pre-creation
 curl -s -D - -N -X POST http://localhost:2026/api/langgraph/runs/stream \
diff --git a/frontend/src/content/en/harness/mcp.mdx b/frontend/src/content/en/harness/mcp.mdx
index b7f37e3b61..9c6218c877 100644
--- a/frontend/src/content/en/harness/mcp.mdx
+++ b/frontend/src/content/en/harness/mcp.mdx
@@ -233,7 +233,7 @@ conversation:
 MCP servers can be managed in several ways:
 
 - **Through the DeerFlow App UI**: the extensions panel shows connected MCP servers and lets you enable/disable them.
-- **Through the Gateway API**: `POST /api/extensions/mcp/{name}/enable` and `/disable`.
+- **Through the Gateway API**: `PATCH /api/mcp/config` with body `{"server_name": "<name>", "enabled": true}` (or `false`; admin only).
 - **By editing `extensions_config.json` directly**: useful for scripted or programmatic configuration.
 
 Changes are picked up automatically due to the file mtime-based cache invalidation.
diff --git a/frontend/src/content/en/harness/skills.mdx b/frontend/src/content/en/harness/skills.mdx
index 0ac29004d4..e92ee13951 100644
--- a/frontend/src/content/en/harness/skills.mdx
+++ b/frontend/src/content/en/harness/skills.mdx
@@ -111,7 +111,7 @@ The `container_path` is important: it tells the agent where to find skill resour
 Skill availability is tracked in `extensions_config.json` (separate from `config.yaml`). You can manage skill state:
 
 - **Through the DeerFlow App UI**: the skills panel lets you toggle skills on and off.
-- **Through the Gateway API**: `POST /api/extensions/skills/{name}/enable` and `/disable`.
+- **Through the Gateway API**: `PUT /api/skills/{name}` with body `{"enabled": true}` or `{"enabled": false}` (admin only).
 - **By editing `extensions_config.json` directly**.
 
 Because `load_skills()` re-reads the extensions config on every call, changes take effect immediately — no server restart required.
diff --git a/frontend/src/content/zh/harness/mcp.mdx b/frontend/src/content/zh/harness/mcp.mdx
index 5d5fbe2dec..c43b964634 100644
--- a/frontend/src/content/zh/harness/mcp.mdx
+++ b/frontend/src/content/zh/harness/mcp.mdx
@@ -108,7 +108,7 @@ OAuth 流程对 Lead Agent 是透明的——它只是调用工具，DeerFlow 
 MCP 服务器可以通过多种方式管理：
 
 - **通过 DeerFlow 应用界面**：扩展面板显示已连接的 MCP 服务器，允许你启用/禁用它们。
-- **通过 Gateway API**：`POST /api/extensions/mcp/{name}/enable` 和 `/disable`。
+- **通过 Gateway API**：`PATCH /api/mcp/config`，请求体为 `{"server_name": "<name>", "enabled": true}`（禁用时为 `false`；仅管理员）。
 - **直接编辑 `extensions_config.json`**：适用于脚本化或程序化配置。
 
 由于基于文件 mtime 的缓存失效机制，更改会自动被检测到。
diff --git a/frontend/src/content/zh/harness/skills.mdx b/frontend/src/content/zh/harness/skills.mdx
index 8cda27409f..1940e0ac5d 100644
--- a/frontend/src/content/zh/harness/skills.mdx
+++ b/frontend/src/content/zh/harness/skills.mdx
@@ -106,7 +106,7 @@ skills:
 技能可用性在 `extensions_config.json` 中跟踪（独立于 `config.yaml`）。你可以管理技能状态：
 
 - **通过 DeerFlow 应用界面**：技能面板允许你切换技能的启用/禁用状态。
-- **通过 Gateway API**：`POST /api/extensions/skills/{name}/enable` 和 `/disable`。
+- **通过 Gateway API**：`PUT /api/skills/{name}`，请求体为 `{"enabled": true}` 或 `{"enabled": false}`（仅管理员）。
 - **直接编辑 `extensions_config.json`**。
 
 由于 `load_skills()` 每次调用都重新读取扩展配置，更改立即生效——无需重启服务器。