From 7bcd3a6cf5a8ce5c10a09ce830a0c530d16c40e7 Mon Sep 17 00:00:00 2001
From: UlengF <djd21036@gmail.com>
Date: Mon, 12 Oct 2026 16:18:21 +0800
Subject: [PATCH 1/6] docs: add bilingual HugeGraph MCP usage guides

---
 .../cn/docs/quickstart/hugegraph-ai/_index.md |   2 +
 .../quickstart/hugegraph-ai/hugegraph-mcp.md  | 218 +++++++++++++++++
 .../en/docs/quickstart/hugegraph-ai/_index.md |   2 +
 .../quickstart/hugegraph-ai/hugegraph-mcp.md  | 225 ++++++++++++++++++
 data/docs_nav.json                            |  14 ++
 5 files changed, 461 insertions(+)
 create mode 100644 content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
 create mode 100644 content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md

diff --git a/content/cn/docs/quickstart/hugegraph-ai/_index.md b/content/cn/docs/quickstart/hugegraph-ai/_index.md
index 68c4232bd8..6028ee7b30 100644
--- a/content/cn/docs/quickstart/hugegraph-ai/_index.md
+++ b/content/cn/docs/quickstart/hugegraph-ai/_index.md
@@ -10,6 +10,7 @@ weight: 3
 
 ## 模块
 
+- [hugegraph-mcp](./hugegraph-mcp.md)：通过 MCP 向 AI 客户端提供图查询、Schema 和受控写入工具。
 - [hugegraph-llm](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-llm)：知识图谱构建、GraphRAG 和自然语言图查询。
 - [hugegraph-ml](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-ml)：从 HugeGraph 读取图数据并运行图学习模型。
 - [hugegraph-python-client](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-python-client)：管理 Schema、图数据和 Gremlin 查询的 Python SDK。
@@ -88,6 +89,7 @@ cd hugegraph-ml/src
 
 ## 后续阅读
 
+- [HugeGraph-MCP](./hugegraph-mcp.md)
 - [HugeGraph-LLM](./hugegraph-llm.md)
 - [HugeGraph-LLM 使用流程](./quick_start.md)
 - [配置参考](./config-reference.md)
diff --git a/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
new file mode 100644
index 0000000000..be847bb61a
--- /dev/null
+++ b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
@@ -0,0 +1,218 @@
+---
+title: "HugeGraph-MCP"
+linkTitle: "HugeGraph-MCP"
+weight: 7
+---
+
+`hugegraph-mcp` 通过 Model Context Protocol（MCP）向 AI 客户端提供 HugeGraph 工具，
+包括 Schema 检查、结构化图查询、受控写入，以及可选的自然语言查询生成和图数据抽取。
+服务使用 STDIO 传输，由 MCP 客户端启动本地进程；它不是 HugeGraph Server，也不提供独立的 HTTP MCP 端口。
+
+普通图查询直接访问 HugeGraph Server。自然语言生成、抽取和向量刷新还需要
+[HugeGraph-LLM](./hugegraph-llm.md) 服务，模型凭据配置在该服务中。
+
+## 环境要求
+
+- Python 3.10 或更高版本；单独运行 HugeGraph-LLM 时，请同时满足该模块的 Python 版本要求。
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) 和支持 STDIO 的 MCP 客户端。
+- 可从 MCP 进程访问的 HugeGraph Server 1.7.0 或更高版本。默认图路径为 `DEFAULT/hugegraph`，使用 graphspace API。
+- 已创建的图及具备相应权限的账号。服务端认证配置见[认证与授权](../../config/config-authentication.md)。
+
+## 安装与连接
+
+以下示例固定使用已发布的 `hugegraph-mcp==1.7.1`，不需要克隆代码仓库。
+将地址、图路径和凭据替换为实际部署值。先使用只读模式验证连接，再按需要开放受支持的写入。
+
+支持 `mcpServers` JSON 配置的客户端可添加：
+
+```json
+{
+  "mcpServers": {
+    "hugegraph": {
+      "command": "uvx",
+      "args": ["hugegraph-mcp@1.7.1"],
+      "env": {
+        "HUGEGRAPH_URL": "http://127.0.0.1:8080",
+        "HUGEGRAPH_GRAPH_PATH": "DEFAULT/hugegraph",
+        "HUGEGRAPH_USER": "your-user",
+        "HUGEGRAPH_PASSWORD": "your-password",
+        "HUGEGRAPH_MCP_READONLY": "true"
+      }
+    }
+  }
+}
+```
+
+不同客户端的配置文件位置和结构可能不同，请按客户端说明填写相同的启动命令、参数和环境变量。
+如果客户端找不到 `uvx`，将 `command` 改为本机 `uvx` 的绝对路径。修改配置后重启 MCP 进程。
+
+也可在已配置上述环境变量的终端中启动：
+
+```bash
+uvx hugegraph-mcp@1.7.1
+```
+
+进程启动后等待 MCP 客户端通过标准输入发送协议消息，不会打开网页。
+stdout 用于 MCP JSON-RPC，不要将额外的 shell 输出写入该通道。
+
+### 验证连接
+
+通过客户端列出工具，再调用 `inspect_graph_tool`。以下 JSON 是 MCP `tools/call` 的参数内容，
+不是向 HugeGraph REST API 直接发送的请求。
+
+```json
+{
+  "name": "inspect_graph_tool",
+  "arguments": {"include_raw_schema": true}
+}
+```
+
+确认返回 `ok=true`、`data.hugegraph_server_status="available"`。
+从 Schema 中选择已有的顶点标签，将下例中的 `person` 替换为该标签：
+
+```json
+{
+  "name": "query_graph_data_tool",
+  "arguments": {
+    "target": "vertex",
+    "operation": "page",
+    "label": "person",
+    "limit": 5
+  }
+}
+```
+
+该工具属于默认的 16 工具集。分页时使用响应中的 `next_page` 作为下一次调用的 `page`，
+并保留相同的查询条件。结果为空不一定表示连接失败，请同时检查图路径、标签和已有数据。
+
+## 工具集与版本
+
+工具集选择的是同一个包提供的工具分组，不是软件包版本、HugeGraph Server 版本或 MCP 协议版本。
+`1.7.1` 的配置名称如下：
+
+| `HUGEGRAPH_MCP_TOOLSET` | 工具数量 | 用途 |
+|---|---|---|
+| 未设置，或 `v2_core` | 16 | 默认工具集，包含结构化查询和持久化写入计划工具 |
+| `v1` | 10 | 兼容工具集，保留较早的工具入口 |
+
+不要填写 `v2`；它不是该版本支持的工具集名称。
+两种工具集的 `mcp_tool_contract_version` 均为 `2.0`，该字段表示工具契约，不表示包版本。
+
+### 新名称迁移（尚未发布）
+
+命名修复将默认工具集改名为 `core`，兼容工具集改名为 `legacy`。
+本节描述待发布的改动，**不适用于上面的 1.7.1 安装命令**。
+新版本号和升级命令应在正式发布后更新。
+
+- `v2_core` 对应 `core`，`v1` 对应 `legacy`；旧值作为兼容别名保留，并输出迁移警告。
+- 检查接口统一返回 `core` 或 `legacy`，比较 `data.toolset` 或 `meta.toolset` 的客户端需要同步调整。
+- 不设置变量时使用 `core`；空白或未知值会阻止启动，不再自动回退到兼容工具集。
+- 工具集在启动时确定，修改配置后需要重启；选择兼容工具集不会绕过权限检查。
+
+## 工具能力
+
+工具已注册不代表所有操作都可以执行。当前能力范围如下，实际工具参数以客户端的工具 Schema 为准。
+
+| 功能 | 工具 | 使用范围 |
+|---|---|---|
+| 检查与设计 | `inspect_graph_tool`、`inspect_schema_tool`、`design_schema_tool` | 查看连接、Schema 和设计指导 |
+| 结构化读取 | `query_graph_data_tool` | 按 ID、ID 列表、分页或条件读取顶点和边 |
+| Schema 创建 | `apply_schema_tool` | 校验和预览；默认工具集支持确认单个属性键、顶点标签或边标签创建 |
+| 写入计划 | `confirm_write_tool`、`get_write_status_tool`、`reconcile_write_tool` | 确认、查询及协调持久化计划 |
+| 图导入 | `import_graph_data_tool` | `extract` 调用 AI；`ingest` 仅预览，`table` 当前禁用 |
+| 图删除 | `delete_graph_data_tool` | 精确边删除可确认；顶点删除仅预览 |
+| 属性变更 | `mutate_graph_properties_tool` | 仅预览，确认当前禁用 |
+| AI 生成与抽取 | `generate_gremlin_tool`、`extract_graph_data_tool` | 生成查询或抽取候选图数据，不自动执行生成的查询 |
+| 向量刷新 | `refresh_vid_embeddings_tool` | 需要 AI、管理模式、允许写入以及显式确认；当前源码的服务侧门禁见下文 |
+| 原始 Gremlin | `execute_gremlin_read_tool`、`execute_gremlin_write_tool` | 当前均返回 `FEATURE_DISABLED`；管理模式不能绕过 |
+
+兼容工具集不包含 `inspect_schema_tool`、`query_graph_data_tool`、`mutate_graph_properties_tool`，
+以及三个写入计划工具。原始 Gremlin 执行也不会因切换到兼容工具集而开放。
+
+### 受控写入
+
+需要写入时，将 `HUGEGRAPH_MCP_READONLY` 设为 `false`，并使用有相应权限的 HugeGraph 账号。
+对于可确认的操作，先执行 dry-run，检查具体目标、变更内容和警告，再使用返回的 `plan_id` 确认：
+
+```json
+{
+  "name": "confirm_write_tool",
+  "arguments": {"plan_id": "<PLAN_ID>"}
+}
+```
+
+用 `get_write_status_tool(plan_id)` 查询持久化结果。`APPLIED` 表示全部操作已确认成功；
+`PARTIAL` 或 `UNKNOWN` 表示部分完成或结果尚不能确定，应先查询和协调状态，不要重新生成计划盲目重试。
+已完成的同一计划再次确认会返回记录的结果，不会重复写入。
+
+内置 SQLite 状态存储要求单个可写 MCP 实例，并需要可持久保存的状态目录。
+多个客户端各自启动进程时，应先保持只读；多实例写入需要另行设计共享事务存储。
+预览返回 `confirmable=false` 的操作不能通过关闭只读或开启管理模式强制执行。
+
+## 配置
+
+下表对应已发布的 `1.7.1`。MCP 图账号与 HugeGraph-LLM 的 API token 是两种不同的凭据。
+
+| 环境变量 | 默认值 | 说明 |
+|---|---|---|
+| `HUGEGRAPH_URL` | `http://127.0.0.1:8080` | MCP 进程访问的 HugeGraph 地址 |
+| `HUGEGRAPH_GRAPH_PATH` | `DEFAULT/hugegraph` | `GRAPH_SPACE/GRAPH_NAME` |
+| `HUGEGRAPH_USER` | `admin` | HugeGraph 用户名 |
+| `HUGEGRAPH_PASSWORD` | 空 | HugeGraph 密码 |
+| `HUGEGRAPH_MCP_TOOLSET` | `v2_core` | 该版本支持 `v2_core`、`v1` |
+| `HUGEGRAPH_MCP_READONLY` | `true` | 禁止受控写入 |
+| `HUGEGRAPH_MCP_ALLOW_AI` | `false` | 允许调用 HugeGraph-LLM |
+| `HUGEGRAPH_MCP_ADMIN_MODE` | `false` | 开放符合条件的管理操作 |
+| `HUGEGRAPH_AI_URL` | `http://127.0.0.1:8001` | HugeGraph-LLM 服务地址 |
+| `HUGEGRAPH_AI_TOKEN` | 未设置 | HugeGraph-LLM bearer token |
+| `HUGEGRAPH_AI_GRAPH_URL` | 未设置 | 不用于改变 AI 服务目标；当前源码已弃用并忽略此项 |
+| `HUGEGRAPH_AI_TIMEOUT_SECONDS` | `30` | AI HTTP 请求超时，单位为秒 |
+| `HUGEGRAPH_MCP_STATE_DIR` | XDG 状态目录或 `~/.local/state/hugegraph-mcp` | 写入计划与回执的持久化目录 |
+
+### 可选 AI 功能
+
+先按 [HugeGraph-LLM 指南](./hugegraph-llm.md) 配置并启动模型服务，再在 MCP 客户端的 `env` 中加入：
+
+```json
+{
+  "HUGEGRAPH_MCP_ALLOW_AI": "true",
+  "HUGEGRAPH_AI_URL": "http://127.0.0.1:8001",
+  "HUGEGRAPH_AI_TOKEN": "your-ai-service-token"
+}
+```
+
+这段内容应合并到前面的 `env` 对象中。生成和抽取可保持只读；向量刷新还要求
+`HUGEGRAPH_MCP_READONLY=false`、`HUGEGRAPH_MCP_ADMIN_MODE=true` 和调用时 `confirm=true`。
+
+如果 MCP 在宿主机运行，而 AI 在容器中运行，二者访问 HugeGraph 的地址可能不同。
+应在 AI 服务侧配置 `GRAPH_URL` 为容器可访问的地址，例如 `http://server:8080`，并设置 `GRAPH_NAME`、`GRAPH_SPACE`
+与 MCP 目标一致；不要让容器通过 `127.0.0.1` 访问宿主机上的图服务。修改 MCP 地址不会修改 AI 服务目标。
+
+**当前 AI 源码的刷新前置条件**：服务侧还需 `ENABLE_LOGIN=true`、`HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true`
+及强 `USER_TOKEN`；MCP 的 `HUGEGRAPH_AI_TOKEN` 必须携带有效认证。旧部署可能没有这些写入门禁，需核对服务版本。
+当前 MCP 源码要求 `GET /vid-embeddings/refresh-capabilities` 返回 `protocol_version=1`，
+再传入预期图名与 graphspace，由服务校验后刷新；缺少协议的旧服务会被拒绝。这不证明两侧连接同一台物理服务器。
+此协议属于当前源码及下一次发行，不是上述已发布 `1.7.1` 安装示例的保证。
+
+使用 MCP 默认目标 `DEFAULT/hugegraph` 时，AI 服务须明确设置 `GRAPH_NAME=hugegraph`、`GRAPH_SPACE=DEFAULT`；未设置或 null 的 graphspace 不通过严格目标校验。
+
+## 常见问题
+
+- **客户端启动后没有工具**：检查 `uvx` 路径、Python 版本和进程 stderr；终端进程等待协议输入是正常行为。
+- **找不到结构化查询工具**：检查是否选择了兼容工具集。`1.7.1` 使用 `v2_core`，也可直接不设置工具集变量。
+- **返回 `FEATURE_DISABLED`**：先检查能力表、只读、AI 和管理开关；部分操作是后端能力限制，不能仅靠修改配置开放。
+- **AI 调用失败**：检查服务地址、token、容器网络和 AI 日志。MCP 返回的服务不可用错误不一定意味着模型已下线。
+- **向量接口返回 400 或 429**：检查提供商的单次输入条数及请求频率限制。每批最大条数和并发请求数是不同限制；
+  应在 HugeGraph-LLM 的向量适配与索引构建路径中处理，而不是更换 MCP 工具集。
+
+工具响应中的 `ok=false` 表示失败，请同时检查 `error.type`、`error.retryable` 和 `warnings`，
+不要只根据 MCP 连接成功或 HTTP 状态判断业务操作成功。
+
+## 后续阅读
+
+- [HugeGraph-LLM](./hugegraph-llm.md)
+- [HugeGraph-MCP 源码与 README](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-mcp)
+- [集成验证](https://github.com/apache/hugegraph-ai/blob/main/hugegraph-mcp/docs/integration.md)
+- [PyPI 发行包](https://pypi.org/project/hugegraph-mcp/)
+
+仓库 `main` 的文档随源码更新。使用固定发行包时，应先核对对应版本；本文安装示例固定为 `1.7.1`。
diff --git a/content/en/docs/quickstart/hugegraph-ai/_index.md b/content/en/docs/quickstart/hugegraph-ai/_index.md
index fc2cb8d810..6eba8f53d5 100644
--- a/content/en/docs/quickstart/hugegraph-ai/_index.md
+++ b/content/en/docs/quickstart/hugegraph-ai/_index.md
@@ -10,6 +10,7 @@ weight: 3
 
 ## Modules
 
+- [hugegraph-mcp](./hugegraph-mcp.md): graph queries, schema tools, and controlled writes for AI clients through MCP.
 - [hugegraph-llm](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-llm): knowledge graph construction, GraphRAG, and natural-language graph queries.
 - [hugegraph-ml](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-ml): reads graph data from HugeGraph and runs graph learning models.
 - [hugegraph-python-client](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-python-client): a Python SDK for managing schemas and graph data and running Gremlin queries.
@@ -88,6 +89,7 @@ Example scripts are under `hugegraph-ml/src/hugegraph_ml/examples/`.
 
 ## Next Steps
 
+- [HugeGraph-MCP](./hugegraph-mcp.md)
 - [HugeGraph-LLM](./hugegraph-llm.md)
 - [HugeGraph-LLM workflow](./quick_start.md)
 - [Configuration reference](./config-reference.md)
diff --git a/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md b/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
new file mode 100644
index 0000000000..7f9f77420b
--- /dev/null
+++ b/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
@@ -0,0 +1,225 @@
+---
+title: "HugeGraph-MCP"
+linkTitle: "HugeGraph-MCP"
+weight: 7
+---
+
+`hugegraph-mcp` exposes HugeGraph tools to AI clients through the Model Context Protocol (MCP).
+It supports schema inspection, structured graph queries, controlled writes, and optional natural-language query generation and graph extraction.
+The MCP client starts a local process and communicates over STDIO. This process is not HugeGraph Server and does not expose an HTTP MCP endpoint.
+
+Ordinary graph queries connect directly to HugeGraph Server. Query generation, extraction, and embedding refresh also require
+[HugeGraph-LLM](./hugegraph-llm.md), where model credentials are configured.
+
+## Requirements
+
+- Python 3.10 or later. A separate HugeGraph-LLM service must also meet that module's Python requirements.
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) and an MCP client that supports STDIO.
+- HugeGraph Server 1.7.0 or later, reachable from the MCP process. The default graph path is `DEFAULT/hugegraph` and uses the graphspace API.
+- An existing graph and an account with the required permissions. See [authentication and authorization](../../config/config-authentication.md).
+
+## Installation and Connection
+
+These examples pin the published `hugegraph-mcp==1.7.1` package. Cloning the repository is not required.
+Replace the address, graph path, and credentials with your deployment values. Verify the connection in read-only mode before enabling supported writes.
+
+For clients that accept a `mcpServers` JSON configuration, add:
+
+```json
+{
+  "mcpServers": {
+    "hugegraph": {
+      "command": "uvx",
+      "args": ["hugegraph-mcp@1.7.1"],
+      "env": {
+        "HUGEGRAPH_URL": "http://127.0.0.1:8080",
+        "HUGEGRAPH_GRAPH_PATH": "DEFAULT/hugegraph",
+        "HUGEGRAPH_USER": "your-user",
+        "HUGEGRAPH_PASSWORD": "your-password",
+        "HUGEGRAPH_MCP_READONLY": "true"
+      }
+    }
+  }
+}
+```
+
+Configuration locations and formats vary between clients. Use your client's instructions to set the same command, arguments, and environment variables.
+If the client cannot find `uvx`, use its absolute path for `command`. Restart the MCP process after changing the configuration.
+
+You can also start it in a terminal with the environment variables above already configured:
+
+```bash
+uvx hugegraph-mcp@1.7.1
+```
+
+The process waits for protocol messages from the MCP client on stdin; it does not open a web page.
+stdout carries MCP JSON-RPC. Do not write extra shell output to that channel.
+
+### Verify the Connection
+
+List tools through the client, then call `inspect_graph_tool`. The following JSON is the parameter body for MCP `tools/call`,
+not a request to send directly to the HugeGraph REST API.
+
+```json
+{
+  "name": "inspect_graph_tool",
+  "arguments": {"include_raw_schema": true}
+}
+```
+
+Check for `ok=true` and `data.hugegraph_server_status="available"`.
+Choose an existing vertex label from the schema and replace `person` below with that label:
+
+```json
+{
+  "name": "query_graph_data_tool",
+  "arguments": {
+    "target": "vertex",
+    "operation": "page",
+    "label": "person",
+    "limit": 5
+  }
+}
+```
+
+This tool belongs to the default set of 16 tools. To paginate, pass the returned `next_page` as `page` on the next call,
+keeping the same query conditions. An empty result does not necessarily mean the connection failed; check the graph path, label, and existing data.
+
+## Toolsets and Versions
+
+A toolset selects a group of tools within the same package. It is not a package version, HugeGraph Server version, or MCP protocol version.
+Version `1.7.1` accepts the following configuration names:
+
+| `HUGEGRAPH_MCP_TOOLSET` | Tools | Purpose |
+|---|---|---|
+| Unset, or `v2_core` | 16 | Default toolset, including structured queries and persistent write-plan tools |
+| `v1` | 10 | Compatibility toolset retaining earlier tool entry points |
+
+Do not use `v2`; it is not a supported toolset name in this release.
+Both toolsets report `mcp_tool_contract_version="2.0"`. This field describes the tool contract, not the package version.
+
+### New Names (Not Yet Released)
+
+The naming fix renames the default toolset to `core` and the compatibility toolset to `legacy`.
+This section describes an unreleased change and **does not apply to the 1.7.1 installation command above**.
+The release version and upgrade command must be updated after publication.
+
+- `v2_core` maps to `core`, and `v1` maps to `legacy`. Old values remain compatibility aliases and emit a migration warning.
+- Inspection reports only `core` or `legacy`. Clients comparing `data.toolset` or `meta.toolset` must update those comparisons.
+- An unset variable selects `core`. Empty or unknown values prevent startup instead of falling back to the compatibility toolset.
+- Toolset selection happens at startup and requires a restart to change. Compatibility mode does not bypass permission checks.
+
+## Tool Capabilities
+
+A registered tool does not imply that every operation is enabled. The current capability boundaries are summarized below.
+Use the tool schema returned to your client for exact parameters.
+
+| Feature | Tools | Scope |
+|---|---|---|
+| Inspection and design | `inspect_graph_tool`, `inspect_schema_tool`, `design_schema_tool` | Connection status, schema, and design guidance |
+| Structured reads | `query_graph_data_tool` | Read vertices and edges by ID, ID list, page, or conditions |
+| Schema creation | `apply_schema_tool` | Validate and preview; the default toolset can confirm one property key, vertex label, or edge label creation |
+| Write plans | `confirm_write_tool`, `get_write_status_tool`, `reconcile_write_tool` | Confirm, inspect, and reconcile persistent plans |
+| Graph import | `import_graph_data_tool` | AI-backed `extract`; preview-only `ingest`; `table` is currently disabled |
+| Graph deletion | `delete_graph_data_tool` | Exact edge deletion can be confirmed; vertex deletion is preview-only |
+| Property changes | `mutate_graph_properties_tool` | Preview-only; confirmation is currently disabled |
+| AI generation and extraction | `generate_gremlin_tool`, `extract_graph_data_tool` | Generate queries or candidate graph data without executing generated queries |
+| Embedding refresh | `refresh_vid_embeddings_tool` | Requires AI, admin mode, writes enabled, and explicit confirmation; see current-source service gates below |
+| Raw Gremlin | `execute_gremlin_read_tool`, `execute_gremlin_write_tool` | Both return `FEATURE_DISABLED`; admin mode cannot override this |
+
+The compatibility toolset excludes `inspect_schema_tool`, `query_graph_data_tool`, `mutate_graph_properties_tool`,
+and the three write-plan tools. Switching to compatibility mode does not enable raw Gremlin execution.
+
+### Controlled Writes
+
+To use writes, set `HUGEGRAPH_MCP_READONLY=false` and use a HugeGraph account with the appropriate permissions.
+For a confirmable operation, first run a dry-run, review its exact targets, changes, and warnings, then confirm the returned `plan_id`:
+
+```json
+{
+  "name": "confirm_write_tool",
+  "arguments": {"plan_id": "<PLAN_ID>"}
+}
+```
+
+Use `get_write_status_tool(plan_id)` to inspect the persisted result. `APPLIED` means all operations are confirmed successful.
+`PARTIAL` or `UNKNOWN` means the workflow is incomplete or its outcome is uncertain. Inspect and reconcile status before retrying;
+do not blindly create a replacement plan. Confirming the same completed plan again returns its recorded result without repeating the write.
+
+The built-in SQLite state store requires a single writable MCP instance and a persistent state directory.
+When multiple clients start separate processes, keep them read-only initially; multi-instance writes require a shared transactional store design.
+Operations returning `confirmable=false` cannot be forced through by disabling read-only mode or enabling admin mode.
+
+## Configuration
+
+The following defaults apply to published version `1.7.1`. HugeGraph credentials and the HugeGraph-LLM API token are separate credentials.
+
+| Environment variable | Default | Description |
+|---|---|---|
+| `HUGEGRAPH_URL` | `http://127.0.0.1:8080` | HugeGraph address reachable from the MCP process |
+| `HUGEGRAPH_GRAPH_PATH` | `DEFAULT/hugegraph` | `GRAPH_SPACE/GRAPH_NAME` |
+| `HUGEGRAPH_USER` | `admin` | HugeGraph user |
+| `HUGEGRAPH_PASSWORD` | Empty | HugeGraph password |
+| `HUGEGRAPH_MCP_TOOLSET` | `v2_core` | This release accepts `v2_core` and `v1` |
+| `HUGEGRAPH_MCP_READONLY` | `true` | Disable controlled writes |
+| `HUGEGRAPH_MCP_ALLOW_AI` | `false` | Allow calls to HugeGraph-LLM |
+| `HUGEGRAPH_MCP_ADMIN_MODE` | `false` | Enable eligible administrative operations |
+| `HUGEGRAPH_AI_URL` | `http://127.0.0.1:8001` | HugeGraph-LLM service address |
+| `HUGEGRAPH_AI_TOKEN` | Unset | HugeGraph-LLM bearer token |
+| `HUGEGRAPH_AI_GRAPH_URL` | Unset | Does not change the AI target; deprecated and ignored in current source |
+| `HUGEGRAPH_AI_TIMEOUT_SECONDS` | `30` | AI HTTP request timeout in seconds |
+| `HUGEGRAPH_MCP_STATE_DIR` | XDG state directory or `~/.local/state/hugegraph-mcp` | Persistent directory for write plans and receipts |
+
+### Optional AI Features
+
+Configure and start the model service using the [HugeGraph-LLM guide](./hugegraph-llm.md), then add these entries to the MCP client's `env`:
+
+```json
+{
+  "HUGEGRAPH_MCP_ALLOW_AI": "true",
+  "HUGEGRAPH_AI_URL": "http://127.0.0.1:8001",
+  "HUGEGRAPH_AI_TOKEN": "your-ai-service-token"
+}
+```
+
+Merge these entries into the earlier `env` object. Generation and extraction can remain read-only.
+Embedding refresh additionally requires `HUGEGRAPH_MCP_READONLY=false`, `HUGEGRAPH_MCP_ADMIN_MODE=true`, and `confirm=true` in the tool call.
+
+If MCP runs on the host and AI runs in a container, they may need different addresses to reach HugeGraph.
+Configure `GRAPH_URL` on the AI service to an address reachable from its container, such as `http://server:8080`.
+Set `GRAPH_NAME` and `GRAPH_SPACE` to match MCP. Do not use the container's `127.0.0.1` to reach the host graph service.
+Changing the MCP address does not reconfigure the AI service target.
+
+**Refresh prerequisites in current AI source**: also set `ENABLE_LOGIN=true` and `HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true`
+on the service, configure a strong `USER_TOKEN`, and provide valid authentication through MCP's `HUGEGRAPH_AI_TOKEN`.
+Older deployments may lack these gates; check the actual service version. Current MCP source requires
+`GET /vid-embeddings/refresh-capabilities` to return `protocol_version=1`, then sends the expected graph
+and graphspace for service-side validation before refreshing. Older services without the protocol are rejected.
+This does not prove both sides connect to the same physical server. The protocol applies to current source and the next release,
+not the published `1.7.1` installation examples above.
+
+For the default MCP target `DEFAULT/hugegraph`, explicitly configure AI `GRAPH_NAME=hugegraph` and `GRAPH_SPACE=DEFAULT`; an unset/null graphspace does not pass the exact target check.
+
+## Troubleshooting
+
+- **No tools after client startup**: check the `uvx` path, Python version, and process stderr. Waiting for protocol input in a terminal is normal.
+- **Structured query tool missing**: check whether the compatibility toolset was selected. For `1.7.1`, use `v2_core` or leave the variable unset.
+- **`FEATURE_DISABLED` response**: check the capability table and read-only, AI, and admin settings.
+  Some operations are disabled because of backend capability limits and cannot be enabled through configuration alone.
+- **AI calls fail**: check the service address, token, container networking, and AI logs. An unavailable-service error does not necessarily mean a model was
+  retired.
+- **Embedding calls return 400 or 429**: check the provider's input-count and request-rate limits.
+  Batch size and concurrent request count are different limits; handle them in HugeGraph-LLM's embedding and index-building paths, not by changing MCP toolsets.
+
+An `ok=false` tool response indicates failure. Inspect `error.type`, `error.retryable`, and `warnings`;
+an established MCP connection or successful HTTP status alone does not prove that a business operation succeeded.
+
+## Next Steps
+
+- [HugeGraph-LLM](./hugegraph-llm.md)
+- [HugeGraph-MCP source and README](https://github.com/apache/hugegraph-ai/tree/main/hugegraph-mcp)
+- [Integration checks](https://github.com/apache/hugegraph-ai/blob/main/hugegraph-mcp/docs/integration.md)
+- [PyPI package](https://pypi.org/project/hugegraph-mcp/)
+
+Documentation on the repository's `main` branch follows source changes. Check version applicability when using a pinned package;
+the installation examples on this page use `1.7.1`.
diff --git a/data/docs_nav.json b/data/docs_nav.json
index d4b4125433..58cc0fa519 100644
--- a/data/docs_nav.json
+++ b/data/docs_nav.json
@@ -103,6 +103,9 @@
             {
               "page": "/docs/quickstart/hugegraph-ai/hugegraph-llm"
             },
+            {
+              "page": "/docs/quickstart/hugegraph-ai/hugegraph-mcp"
+            },
             {
               "page": "/docs/quickstart/hugegraph-ai/hugegraph-ml"
             },
@@ -504,6 +507,11 @@
               "url": "/docs/quickstart/hugegraph-ai/hugegraph-llm/",
               "children": []
             },
+            {
+              "page": "/docs/quickstart/hugegraph-ai/hugegraph-mcp",
+              "url": "/docs/quickstart/hugegraph-ai/hugegraph-mcp/",
+              "children": []
+            },
             {
               "page": "/docs/quickstart/hugegraph-ai/hugegraph-ml",
               "url": "/docs/quickstart/hugegraph-ai/hugegraph-ml/",
@@ -1001,6 +1009,11 @@
       "/docs/quickstart/hugegraph-ai/",
       "/docs/quickstart/hugegraph-ai/hugegraph-llm/"
     ],
+    "/docs/quickstart/hugegraph-ai/hugegraph-mcp/": [
+      "@group/components",
+      "/docs/quickstart/hugegraph-ai/",
+      "/docs/quickstart/hugegraph-ai/hugegraph-mcp/"
+    ],
     "/docs/quickstart/hugegraph-ai/hugegraph-ml/": [
       "@group/components",
       "/docs/quickstart/hugegraph-ai/",
@@ -1377,6 +1390,7 @@
     "/docs/quickstart/hugegraph-ai/": [
       "/docs/quickstart/hugegraph-ai/quick_start",
       "/docs/quickstart/hugegraph-ai/hugegraph-llm",
+      "/docs/quickstart/hugegraph-ai/hugegraph-mcp",
       "/docs/quickstart/hugegraph-ai/hugegraph-ml",
       "/docs/quickstart/hugegraph-ai/config-reference",
       "/docs/quickstart/hugegraph-ai/rest-api"

From b1561adf57c7b6ad2695bd63c862c101bc493d84 Mon Sep 17 00:00:00 2001
From: imbajin <jin@apache.org>
Date: Sat, 17 Oct 2026 21:50:58 +0800
Subject: [PATCH 2/6] Address review comments on MCP configuration, toolset
 fallback, and navigation baselines

---
 .../quickstart/hugegraph-ai/hugegraph-mcp.md  | 23 +++++++++--------
 .../quickstart/hugegraph-ai/hugegraph-mcp.md  | 25 ++++++++++---------
 scripts/versioning.py                         | 10 ++++----
 3 files changed, 30 insertions(+), 28 deletions(-)

diff --git a/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
index be847bb61a..9367369d9b 100644
--- a/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
+++ b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
@@ -95,13 +95,13 @@ stdout 用于 MCP JSON-RPC，不要将额外的 shell 输出写入该通道。
 | 未设置，或 `v2_core` | 16 | 默认工具集，包含结构化查询和持久化写入计划工具 |
 | `v1` | 10 | 兼容工具集，保留较早的工具入口 |
 
-不要填写 `v2`；它不是该版本支持的工具集名称。
+其他任何值（包括 `v2`、`core`、`legacy` 或空字符串），在 1.7.1 中均会记录错误日志并回退到包含 10 个工具的 `v1` 兼容工具集。
 两种工具集的 `mcp_tool_contract_version` 均为 `2.0`，该字段表示工具契约，不表示包版本。
 
-### 新名称迁移（尚未发布）
+### 新名称迁移（apache/hugegraph-ai#382 提案，尚未合并）
 
-命名修复将默认工具集改名为 `core`，兼容工具集改名为 `legacy`。
-本节描述待发布的改动，**不适用于上面的 1.7.1 安装命令**。
+该提案计划将默认工具集改名为 `core`，兼容工具集改名为 `legacy`。
+本节描述尚未合并的改动，**不适用于上面的 1.7.1 安装命令**。
 新版本号和升级命令应在正式发布后更新。
 
 - `v2_core` 对应 `core`，`v1` 对应 `legacy`；旧值作为兼容别名保留，并输出迁移警告。
@@ -157,6 +157,8 @@ stdout 用于 MCP JSON-RPC，不要将额外的 shell 输出写入该通道。
 |---|---|---|
 | `HUGEGRAPH_URL` | `http://127.0.0.1:8080` | MCP 进程访问的 HugeGraph 地址 |
 | `HUGEGRAPH_GRAPH_PATH` | `DEFAULT/hugegraph` | `GRAPH_SPACE/GRAPH_NAME` |
+| `HUGEGRAPH_GRAPHSPACE` | 未设置 | 覆盖 `HUGEGRAPH_GRAPH_PATH` 中的 graphspace |
+| `HUGEGRAPH_GRAPH` | 未设置 | 覆盖 `HUGEGRAPH_GRAPH_PATH` 中的图名 |
 | `HUGEGRAPH_USER` | `admin` | HugeGraph 用户名 |
 | `HUGEGRAPH_PASSWORD` | 空 | HugeGraph 密码 |
 | `HUGEGRAPH_MCP_TOOLSET` | `v2_core` | 该版本支持 `v2_core`、`v1` |
@@ -165,7 +167,7 @@ stdout 用于 MCP JSON-RPC，不要将额外的 shell 输出写入该通道。
 | `HUGEGRAPH_MCP_ADMIN_MODE` | `false` | 开放符合条件的管理操作 |
 | `HUGEGRAPH_AI_URL` | `http://127.0.0.1:8001` | HugeGraph-LLM 服务地址 |
 | `HUGEGRAPH_AI_TOKEN` | 未设置 | HugeGraph-LLM bearer token |
-| `HUGEGRAPH_AI_GRAPH_URL` | 未设置 | 不用于改变 AI 服务目标；当前源码已弃用并忽略此项 |
+| `HUGEGRAPH_AI_GRAPH_URL` | 未设置 | 不用于改变 AI 服务目标；当前源码已忽略此项 |
 | `HUGEGRAPH_AI_TIMEOUT_SECONDS` | `30` | AI HTTP 请求超时，单位为秒 |
 | `HUGEGRAPH_MCP_STATE_DIR` | XDG 状态目录或 `~/.local/state/hugegraph-mcp` | 写入计划与回执的持久化目录 |
 
@@ -188,13 +190,12 @@ stdout 用于 MCP JSON-RPC，不要将额外的 shell 输出写入该通道。
 应在 AI 服务侧配置 `GRAPH_URL` 为容器可访问的地址，例如 `http://server:8080`，并设置 `GRAPH_NAME`、`GRAPH_SPACE`
 与 MCP 目标一致；不要让容器通过 `127.0.0.1` 访问宿主机上的图服务。修改 MCP 地址不会修改 AI 服务目标。
 
-**当前 AI 源码的刷新前置条件**：服务侧还需 `ENABLE_LOGIN=true`、`HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true`
+**AI 提案中的刷新前置条件**：服务侧还需 `ENABLE_LOGIN=true`、`HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true`
 及强 `USER_TOKEN`；MCP 的 `HUGEGRAPH_AI_TOKEN` 必须携带有效认证。旧部署可能没有这些写入门禁，需核对服务版本。
-当前 MCP 源码要求 `GET /vid-embeddings/refresh-capabilities` 返回 `protocol_version=1`，
-再传入预期图名与 graphspace，由服务校验后刷新；缺少协议的旧服务会被拒绝。这不证明两侧连接同一台物理服务器。
-此协议属于当前源码及下一次发行，不是上述已发布 `1.7.1` 安装示例的保证。
-
-使用 MCP 默认目标 `DEFAULT/hugegraph` 时，AI 服务须明确设置 `GRAPH_NAME=hugegraph`、`GRAPH_SPACE=DEFAULT`；未设置或 null 的 graphspace 不通过严格目标校验。
+在尚未合并的提案 [apache/hugegraph-ai#382](https://github.com/apache/hugegraph-ai/pull/382) 中，MCP 要求
+`GET /vid-embeddings/refresh-capabilities` 返回 `protocol_version=1`，再传入预期图名与 graphspace
+由服务校验后刷新；缺少协议的旧服务会被拒绝。这不证明两侧连接同一台物理服务器。此协议属于后续版本规划，
+不适用于上述已发布的 `1.7.1` 安装示例。
 
 ## 常见问题
 
diff --git a/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md b/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
index 7f9f77420b..222b7a5785 100644
--- a/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
+++ b/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
@@ -95,13 +95,13 @@ Version `1.7.1` accepts the following configuration names:
 | Unset, or `v2_core` | 16 | Default toolset, including structured queries and persistent write-plan tools |
 | `v1` | 10 | Compatibility toolset retaining earlier tool entry points |
 
-Do not use `v2`; it is not a supported toolset name in this release.
+Any other value, including `v2`, `core`, `legacy` or an empty string, falls back to the 10-tool `v1` set in 1.7.1 and logs an error.
 Both toolsets report `mcp_tool_contract_version="2.0"`. This field describes the tool contract, not the package version.
 
-### New Names (Not Yet Released)
+### New Names (Proposed in apache/hugegraph-ai#382)
 
-The naming fix renames the default toolset to `core` and the compatibility toolset to `legacy`.
-This section describes an unreleased change and **does not apply to the 1.7.1 installation command above**.
+The proposed naming fix renames the default toolset to `core` and the compatibility toolset to `legacy`.
+This section describes an unmerged change and **does not apply to the 1.7.1 installation command above**.
 The release version and upgrade command must be updated after publication.
 
 - `v2_core` maps to `core`, and `v1` maps to `legacy`. Old values remain compatibility aliases and emit a migration warning.
@@ -123,8 +123,8 @@ Use the tool schema returned to your client for exact parameters.
 | Graph import | `import_graph_data_tool` | AI-backed `extract`; preview-only `ingest`; `table` is currently disabled |
 | Graph deletion | `delete_graph_data_tool` | Exact edge deletion can be confirmed; vertex deletion is preview-only |
 | Property changes | `mutate_graph_properties_tool` | Preview-only; confirmation is currently disabled |
-| AI generation and extraction | `generate_gremlin_tool`, `extract_graph_data_tool` | Generate queries or candidate graph data without executing generated queries |
-| Embedding refresh | `refresh_vid_embeddings_tool` | Requires AI, admin mode, writes enabled, and explicit confirmation; see current-source service gates below |
+| AI generation and extraction | `generate_gremlin_tool`, `extract_graph_data_tool` | Generate queries or graph data without executing generated queries |
+| Embedding refresh | `refresh_vid_embeddings_tool` | Requires AI, admin mode, writes enabled, and confirmation; see service gates below |
 | Raw Gremlin | `execute_gremlin_read_tool`, `execute_gremlin_write_tool` | Both return `FEATURE_DISABLED`; admin mode cannot override this |
 
 The compatibility toolset excludes `inspect_schema_tool`, `query_graph_data_tool`, `mutate_graph_properties_tool`,
@@ -158,6 +158,8 @@ The following defaults apply to published version `1.7.1`. HugeGraph credentials
 |---|---|---|
 | `HUGEGRAPH_URL` | `http://127.0.0.1:8080` | HugeGraph address reachable from the MCP process |
 | `HUGEGRAPH_GRAPH_PATH` | `DEFAULT/hugegraph` | `GRAPH_SPACE/GRAPH_NAME` |
+| `HUGEGRAPH_GRAPHSPACE` | Unset | Overrides the graphspace in `HUGEGRAPH_GRAPH_PATH` |
+| `HUGEGRAPH_GRAPH` | Unset | Overrides the graph name in `HUGEGRAPH_GRAPH_PATH` |
 | `HUGEGRAPH_USER` | `admin` | HugeGraph user |
 | `HUGEGRAPH_PASSWORD` | Empty | HugeGraph password |
 | `HUGEGRAPH_MCP_TOOLSET` | `v2_core` | This release accepts `v2_core` and `v1` |
@@ -166,7 +168,7 @@ The following defaults apply to published version `1.7.1`. HugeGraph credentials
 | `HUGEGRAPH_MCP_ADMIN_MODE` | `false` | Enable eligible administrative operations |
 | `HUGEGRAPH_AI_URL` | `http://127.0.0.1:8001` | HugeGraph-LLM service address |
 | `HUGEGRAPH_AI_TOKEN` | Unset | HugeGraph-LLM bearer token |
-| `HUGEGRAPH_AI_GRAPH_URL` | Unset | Does not change the AI target; deprecated and ignored in current source |
+| `HUGEGRAPH_AI_GRAPH_URL` | Unset | Does not change the AI target; ignored in current source |
 | `HUGEGRAPH_AI_TIMEOUT_SECONDS` | `30` | AI HTTP request timeout in seconds |
 | `HUGEGRAPH_MCP_STATE_DIR` | XDG state directory or `~/.local/state/hugegraph-mcp` | Persistent directory for write plans and receipts |
 
@@ -190,16 +192,15 @@ Configure `GRAPH_URL` on the AI service to an address reachable from its contain
 Set `GRAPH_NAME` and `GRAPH_SPACE` to match MCP. Do not use the container's `127.0.0.1` to reach the host graph service.
 Changing the MCP address does not reconfigure the AI service target.
 
-**Refresh prerequisites in current AI source**: also set `ENABLE_LOGIN=true` and `HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true`
+**Refresh prerequisites in proposed AI changes**: also set `ENABLE_LOGIN=true` and `HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true`
 on the service, configure a strong `USER_TOKEN`, and provide valid authentication through MCP's `HUGEGRAPH_AI_TOKEN`.
-Older deployments may lack these gates; check the actual service version. Current MCP source requires
+Older deployments may lack these gates; check the actual service version. The proposed refresh protocol in
+[apache/hugegraph-ai#382](https://github.com/apache/hugegraph-ai/pull/382) (not yet merged) requires
 `GET /vid-embeddings/refresh-capabilities` to return `protocol_version=1`, then sends the expected graph
 and graphspace for service-side validation before refreshing. Older services without the protocol are rejected.
-This does not prove both sides connect to the same physical server. The protocol applies to current source and the next release,
+This does not prove both sides connect to the same physical server. The protocol applies to future releases,
 not the published `1.7.1` installation examples above.
 
-For the default MCP target `DEFAULT/hugegraph`, explicitly configure AI `GRAPH_NAME=hugegraph` and `GRAPH_SPACE=DEFAULT`; an unset/null graphspace does not pass the exact target check.
-
 ## Troubleshooting
 
 - **No tools after client startup**: check the `uvx` path, Python version, and process stderr. Waiting for protocol input in a terminal is normal.
diff --git a/scripts/versioning.py b/scripts/versioning.py
index cdcc656d8f..0c023b2464 100644
--- a/scripts/versioning.py
+++ b/scripts/versioning.py
@@ -133,29 +133,29 @@
 DOCS_NAV_EXPECTED_STATS = {
     "latest": {
         "groups": 5,
-        "pages": 95,
+        "pages": 96,
         "removed": 4,
         "scopedLinks": 0,
-        "treeSha256": "b33f771f77fc376121902fee37d66235d2920a450320620400320925f985c86a",
+        "treeSha256": "8b2b1f270a27b909b673a30d186c46a6a0feccab4c4a980d9b8127686346be2b",
     },
     "1.7": {
         "groups": 5,
         "pages": 85,
-        "removed": 8,
+        "removed": 9,
         "scopedLinks": 10,
         "treeSha256": "c87538b82b0e3506eef59417411686ddc188e0f33d0e3a1cda687de8d6f88747",
     },
     "1.5": {
         "groups": 5,
         "pages": 77,
-        "removed": 16,
+        "removed": 17,
         "scopedLinks": 10,
         "treeSha256": "ac29ab8f0e7020496a3a1afe480687043d751e32c93ffb848e2210e3500cd483",
     },
     "1.3": {
         "groups": 5,
         "pages": 68,
-        "removed": 25,
+        "removed": 26,
         "scopedLinks": 10,
         "treeSha256": "e8c9b0a64dac6dd3e47827ec5072697eb7d3ed79659e0b5c4a9c5df8e1408d38",
     },

From 5ec34e7f8387f7cc1bcaee597a736271e44ede91 Mon Sep 17 00:00:00 2001
From: imbajin <jin@apache.org>
Date: Sun, 18 Oct 2026 20:14:25 +0800
Subject: [PATCH 3/6] docs(mcp): add version routes and update #382 merge
 status

---
 .../docs/quickstart/hugegraph-ai/hugegraph-mcp.md  | 10 +++++-----
 .../docs/quickstart/hugegraph-ai/hugegraph-mcp.md  | 10 +++++-----
 data/version_routes.json                           | 14 ++++++++++++++
 3 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
index 9367369d9b..574c9d7114 100644
--- a/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
+++ b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
@@ -98,10 +98,10 @@ stdout 用于 MCP JSON-RPC，不要将额外的 shell 输出写入该通道。
 其他任何值（包括 `v2`、`core`、`legacy` 或空字符串），在 1.7.1 中均会记录错误日志并回退到包含 10 个工具的 `v1` 兼容工具集。
 两种工具集的 `mcp_tool_contract_version` 均为 `2.0`，该字段表示工具契约，不表示包版本。
 
-### 新名称迁移（apache/hugegraph-ai#382 提案，尚未合并）
+### 新名称迁移（已合并至 apache/hugegraph-ai main #382，未发布）
 
-该提案计划将默认工具集改名为 `core`，兼容工具集改名为 `legacy`。
-本节描述尚未合并的改动，**不适用于上面的 1.7.1 安装命令**。
+该改动将默认工具集改名为 `core`，兼容工具集改名为 `legacy`。
+该改动已合并至 apache/hugegraph-ai main 分支（#382），但尚未发布至 PyPI，**不适用于上面的 1.7.1 安装命令**。
 新版本号和升级命令应在正式发布后更新。
 
 - `v2_core` 对应 `core`，`v1` 对应 `legacy`；旧值作为兼容别名保留，并输出迁移警告。
@@ -190,9 +190,9 @@ stdout 用于 MCP JSON-RPC，不要将额外的 shell 输出写入该通道。
 应在 AI 服务侧配置 `GRAPH_URL` 为容器可访问的地址，例如 `http://server:8080`，并设置 `GRAPH_NAME`、`GRAPH_SPACE`
 与 MCP 目标一致；不要让容器通过 `127.0.0.1` 访问宿主机上的图服务。修改 MCP 地址不会修改 AI 服务目标。
 
-**AI 提案中的刷新前置条件**：服务侧还需 `ENABLE_LOGIN=true`、`HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true`
+**#382 中的刷新前置条件（已合并至 main，未发布）**：服务侧还需 `ENABLE_LOGIN=true`、`HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true`
 及强 `USER_TOKEN`；MCP 的 `HUGEGRAPH_AI_TOKEN` 必须携带有效认证。旧部署可能没有这些写入门禁，需核对服务版本。
-在尚未合并的提案 [apache/hugegraph-ai#382](https://github.com/apache/hugegraph-ai/pull/382) 中，MCP 要求
+在 [apache/hugegraph-ai#382](https://github.com/apache/hugegraph-ai/pull/382)（已合并至 main，未正式发版）中，MCP 要求
 `GET /vid-embeddings/refresh-capabilities` 返回 `protocol_version=1`，再传入预期图名与 graphspace
 由服务校验后刷新；缺少协议的旧服务会被拒绝。这不证明两侧连接同一台物理服务器。此协议属于后续版本规划，
 不适用于上述已发布的 `1.7.1` 安装示例。
diff --git a/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md b/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
index 222b7a5785..df48b51d51 100644
--- a/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
+++ b/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
@@ -98,10 +98,10 @@ Version `1.7.1` accepts the following configuration names:
 Any other value, including `v2`, `core`, `legacy` or an empty string, falls back to the 10-tool `v1` set in 1.7.1 and logs an error.
 Both toolsets report `mcp_tool_contract_version="2.0"`. This field describes the tool contract, not the package version.
 
-### New Names (Proposed in apache/hugegraph-ai#382)
+### New Names (Merged to apache/hugegraph-ai main in #382)
 
 The proposed naming fix renames the default toolset to `core` and the compatibility toolset to `legacy`.
-This section describes an unmerged change and **does not apply to the 1.7.1 installation command above**.
+This change is merged to apache/hugegraph-ai main in #382, but is not yet in a published release; it **does not apply to the 1.7.1 installation command above**.
 The release version and upgrade command must be updated after publication.
 
 - `v2_core` maps to `core`, and `v1` maps to `legacy`. Old values remain compatibility aliases and emit a migration warning.
@@ -192,10 +192,10 @@ Configure `GRAPH_URL` on the AI service to an address reachable from its contain
 Set `GRAPH_NAME` and `GRAPH_SPACE` to match MCP. Do not use the container's `127.0.0.1` to reach the host graph service.
 Changing the MCP address does not reconfigure the AI service target.
 
-**Refresh prerequisites in proposed AI changes**: also set `ENABLE_LOGIN=true` and `HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true`
+**Refresh prerequisites in #382 (merged to main, not yet in a published release)**: also set `ENABLE_LOGIN=true` and `HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true`
 on the service, configure a strong `USER_TOKEN`, and provide valid authentication through MCP's `HUGEGRAPH_AI_TOKEN`.
-Older deployments may lack these gates; check the actual service version. The proposed refresh protocol in
-[apache/hugegraph-ai#382](https://github.com/apache/hugegraph-ai/pull/382) (not yet merged) requires
+Older deployments may lack these gates; check the actual service version. The refresh protocol merged in
+[apache/hugegraph-ai#382](https://github.com/apache/hugegraph-ai/pull/382) (not yet in a published release) requires
 `GET /vid-embeddings/refresh-capabilities` to return `protocol_version=1`, then sends the expected graph
 and graphspace for service-side validation before refreshing. Older services without the protocol are rejected.
 This does not prove both sides connect to the same physical server. The protocol applies to future releases,
diff --git a/data/version_routes.json b/data/version_routes.json
index 46ae1f6fa0..ababc70959 100644
--- a/data/version_routes.json
+++ b/data/version_routes.json
@@ -687,6 +687,13 @@
       "1.3": null,
       "1.0": null
     },
+    "cn:quickstart/hugegraph-ai/hugegraph-mcp": {
+      "latest": "cn/docs/quickstart/hugegraph-ai/hugegraph-mcp/",
+      "1.7": null,
+      "1.5": null,
+      "1.3": null,
+      "1.0": null
+    },
     "cn:quickstart/hugegraph-ai/hugegraph-ml": {
       "latest": "cn/docs/quickstart/hugegraph-ai/hugegraph-ml/",
       "1.7": "cn/docs/quickstart/hugegraph-ai/hugegraph-ml/",
@@ -1429,6 +1436,13 @@
       "1.3": null,
       "1.0": null
     },
+    "en:quickstart/hugegraph-ai/hugegraph-mcp": {
+      "latest": "docs/quickstart/hugegraph-ai/hugegraph-mcp/",
+      "1.7": null,
+      "1.5": null,
+      "1.3": null,
+      "1.0": null
+    },
     "en:quickstart/hugegraph-ai/hugegraph-ml": {
       "latest": "docs/quickstart/hugegraph-ai/hugegraph-ml/",
       "1.7": "docs/quickstart/hugegraph-ai/hugegraph-ml/",

From 0bef46175bb6b6e484cd59a1500a85e48eced046 Mon Sep 17 00:00:00 2001
From: imbajin <jin@apache.org>
Date: Tue, 20 Oct 2026 03:39:38 +0800
Subject: [PATCH 4/6] docs: align MCP toolset rename and split refresh service
 gates

---
 .../quickstart/hugegraph-ai/hugegraph-mcp.md  | 16 ++++++-------
 .../quickstart/hugegraph-ai/hugegraph-mcp.md  | 23 ++++++++++---------
 2 files changed, 20 insertions(+), 19 deletions(-)

diff --git a/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
index 574c9d7114..4bab72b042 100644
--- a/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
+++ b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
@@ -183,19 +183,19 @@ stdout 用于 MCP JSON-RPC，不要将额外的 shell 输出写入该通道。
 }
 ```
 
-这段内容应合并到前面的 `env` 对象中。生成和抽取可保持只读；向量刷新还要求
-`HUGEGRAPH_MCP_READONLY=false`、`HUGEGRAPH_MCP_ADMIN_MODE=true` 和调用时 `confirm=true`。
+这段内容应合并到前面的 `env` 对象中。生成和抽取可保持只读；向量刷新要求满足以下条件：
+- 客户端配置：`HUGEGRAPH_MCP_READONLY=false`、`HUGEGRAPH_MCP_ADMIN_MODE=true`，且调用时需传入 `confirm=true`。
+- 服务端配置（HugeGraph-LLM）：需设置 `ENABLE_LOGIN=true` 与 `HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true`，配置强 `USER_TOKEN`，
+  并通过 MCP 的 `HUGEGRAPH_AI_TOKEN` 传递有效认证。若服务端未开启写入门禁，刷新请求将被拒绝并返回 `FEATURE_DISABLED`（"Legacy Thin API writes are disabled"）。
 
 如果 MCP 在宿主机运行，而 AI 在容器中运行，二者访问 HugeGraph 的地址可能不同。
 应在 AI 服务侧配置 `GRAPH_URL` 为容器可访问的地址，例如 `http://server:8080`，并设置 `GRAPH_NAME`、`GRAPH_SPACE`
 与 MCP 目标一致；不要让容器通过 `127.0.0.1` 访问宿主机上的图服务。修改 MCP 地址不会修改 AI 服务目标。
 
-**#382 中的刷新前置条件（已合并至 main，未发布）**：服务侧还需 `ENABLE_LOGIN=true`、`HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true`
-及强 `USER_TOKEN`；MCP 的 `HUGEGRAPH_AI_TOKEN` 必须携带有效认证。旧部署可能没有这些写入门禁，需核对服务版本。
-在 [apache/hugegraph-ai#382](https://github.com/apache/hugegraph-ai/pull/382)（已合并至 main，未正式发版）中，MCP 要求
-`GET /vid-embeddings/refresh-capabilities` 返回 `protocol_version=1`，再传入预期图名与 graphspace
-由服务校验后刷新；缺少协议的旧服务会被拒绝。这不证明两侧连接同一台物理服务器。此协议属于后续版本规划，
-不适用于上述已发布的 `1.7.1` 安装示例。
+**能力校验协议（已合并至 main #382，未正式发布）**：
+在 [apache/hugegraph-ai#382](https://github.com/apache/hugegraph-ai/pull/382) 中，MCP 增加了双向校验协议，要求
+`GET /vid-embeddings/refresh-capabilities` 返回 `protocol_version=1`，并在刷新前传递预期图名与 graphspace 由服务端校验；
+缺少该协议的服务将被拒绝。此协议属于后续版本规划，不适用于上述已发布的 `1.7.1` 安装示例。
 
 ## 常见问题
 
diff --git a/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md b/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
index df48b51d51..67504bb98b 100644
--- a/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
+++ b/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
@@ -98,9 +98,9 @@ Version `1.7.1` accepts the following configuration names:
 Any other value, including `v2`, `core`, `legacy` or an empty string, falls back to the 10-tool `v1` set in 1.7.1 and logs an error.
 Both toolsets report `mcp_tool_contract_version="2.0"`. This field describes the tool contract, not the package version.
 
-### New Names (Merged to apache/hugegraph-ai main in #382)
+### New Names (Merged to apache/hugegraph-ai main in #382, Not Yet Released)
 
-The proposed naming fix renames the default toolset to `core` and the compatibility toolset to `legacy`.
+The default toolset is renamed to `core` and the compatibility toolset to `legacy`.
 This change is merged to apache/hugegraph-ai main in #382, but is not yet in a published release; it **does not apply to the 1.7.1 installation command above**.
 The release version and upgrade command must be updated after publication.
 
@@ -185,21 +185,22 @@ Configure and start the model service using the [HugeGraph-LLM guide](./hugegrap
 ```
 
 Merge these entries into the earlier `env` object. Generation and extraction can remain read-only.
-Embedding refresh additionally requires `HUGEGRAPH_MCP_READONLY=false`, `HUGEGRAPH_MCP_ADMIN_MODE=true`, and `confirm=true` in the tool call.
+Embedding refresh additionally requires:
+- Client settings: `HUGEGRAPH_MCP_READONLY=false`, `HUGEGRAPH_MCP_ADMIN_MODE=true`, and `confirm=true` in the tool call.
+- Service settings (HugeGraph-LLM): `ENABLE_LOGIN=true`, `HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true`, a configured `USER_TOKEN`,
+  and valid authentication passed via MCP's `HUGEGRAPH_AI_TOKEN`. Without these service-side gates, refresh requests are rejected
+  with `FEATURE_DISABLED` ("Legacy Thin API writes are disabled").
 
 If MCP runs on the host and AI runs in a container, they may need different addresses to reach HugeGraph.
 Configure `GRAPH_URL` on the AI service to an address reachable from its container, such as `http://server:8080`.
 Set `GRAPH_NAME` and `GRAPH_SPACE` to match MCP. Do not use the container's `127.0.0.1` to reach the host graph service.
 Changing the MCP address does not reconfigure the AI service target.
 
-**Refresh prerequisites in #382 (merged to main, not yet in a published release)**: also set `ENABLE_LOGIN=true` and `HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true`
-on the service, configure a strong `USER_TOKEN`, and provide valid authentication through MCP's `HUGEGRAPH_AI_TOKEN`.
-Older deployments may lack these gates; check the actual service version. The refresh protocol merged in
-[apache/hugegraph-ai#382](https://github.com/apache/hugegraph-ai/pull/382) (not yet in a published release) requires
-`GET /vid-embeddings/refresh-capabilities` to return `protocol_version=1`, then sends the expected graph
-and graphspace for service-side validation before refreshing. Older services without the protocol are rejected.
-This does not prove both sides connect to the same physical server. The protocol applies to future releases,
-not the published `1.7.1` installation examples above.
+**Capability check protocol in #382 (merged to main, not yet in a published release)**:
+The capability check protocol merged in [apache/hugegraph-ai#382](https://github.com/apache/hugegraph-ai/pull/382) requires
+`GET /vid-embeddings/refresh-capabilities` to return `protocol_version=1`, and sends the expected graph and graphspace
+for service-side validation before refreshing. Services lacking this protocol are rejected. This protocol applies to future
+releases and is not required for the published `1.7.1` package.
 
 ## Troubleshooting
 

From 9a177b46aae167daa4c785d01376bd3478908f12 Mon Sep 17 00:00:00 2001
From: dark <jin@apache.org>
Date: Fri, 30 Oct 2026 05:12:54 +0800
Subject: [PATCH 5/6] docs(mcp): refine toolset evolution and capability
 protocol descriptions

---
 .../quickstart/hugegraph-ai/hugegraph-mcp.md  | 20 +++++++-----------
 .../quickstart/hugegraph-ai/hugegraph-mcp.md  | 21 +++++++------------
 2 files changed, 16 insertions(+), 25 deletions(-)

diff --git a/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
index 4bab72b042..10248161d2 100644
--- a/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
+++ b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
@@ -98,16 +98,14 @@ stdout 用于 MCP JSON-RPC，不要将额外的 shell 输出写入该通道。
 其他任何值（包括 `v2`、`core`、`legacy` 或空字符串），在 1.7.1 中均会记录错误日志并回退到包含 10 个工具的 `v1` 兼容工具集。
 两种工具集的 `mcp_tool_contract_version` 均为 `2.0`，该字段表示工具契约，不表示包版本。
 
-### 新名称迁移（已合并至 apache/hugegraph-ai main #382，未发布）
+### 工具集命名演进 {#toolset-evolution}
 
-该改动将默认工具集改名为 `core`，兼容工具集改名为 `legacy`。
-该改动已合并至 apache/hugegraph-ai main 分支（#382），但尚未发布至 PyPI，**不适用于上面的 1.7.1 安装命令**。
-新版本号和升级命令应在正式发布后更新。
+最新源码已将默认工具集更名为 `core`，兼容工具集更名为 `legacy`。该规范将在后续版本正式发布；若使用 `1.7.1` 安装包，请继续遵循上述配置。
 
-- `v2_core` 对应 `core`，`v1` 对应 `legacy`；旧值作为兼容别名保留，并输出迁移警告。
-- 检查接口统一返回 `core` 或 `legacy`，比较 `data.toolset` 或 `meta.toolset` 的客户端需要同步调整。
-- 不设置变量时使用 `core`；空白或未知值会阻止启动，不再自动回退到兼容工具集。
-- 工具集在启动时确定，修改配置后需要重启；选择兼容工具集不会绕过权限检查。
+- `v2_core` 对应新版 `core`，`v1` 对应新版 `legacy`；旧名称作为兼容别名保留，使用时将输出迁移提示。
+- 检查接口统一返回 `core` 或 `legacy`，依赖 `data.toolset` 或 `meta.toolset` 的客户端需同步适配。
+- 未设置变量时默认启用 `core`；空值或未知值将直接拦截启动，不再静默回退。
+- 工具集在启动时加载，变更配置后需重启客户端；切换兼容工具集不会绕过鉴权与只读约束。
 
 ## 工具能力
 
@@ -192,10 +190,8 @@ stdout 用于 MCP JSON-RPC，不要将额外的 shell 输出写入该通道。
 应在 AI 服务侧配置 `GRAPH_URL` 为容器可访问的地址，例如 `http://server:8080`，并设置 `GRAPH_NAME`、`GRAPH_SPACE`
 与 MCP 目标一致；不要让容器通过 `127.0.0.1` 访问宿主机上的图服务。修改 MCP 地址不会修改 AI 服务目标。
 
-**能力校验协议（已合并至 main #382，未正式发布）**：
-在 [apache/hugegraph-ai#382](https://github.com/apache/hugegraph-ai/pull/382) 中，MCP 增加了双向校验协议，要求
-`GET /vid-embeddings/refresh-capabilities` 返回 `protocol_version=1`，并在刷新前传递预期图名与 graphspace 由服务端校验；
-缺少该协议的服务将被拒绝。此协议属于后续版本规划，不适用于上述已发布的 `1.7.1` 安装示例。
+**能力校验协议**：
+新版协议要求调用 `GET /vid-embeddings/refresh-capabilities` 返回 `protocol_version=1`，并在刷新前传递预期图名与 graphspace 由服务端进行合法性校验；不支持该协议的服务将被拒绝。该机制用于保障多租户与图空间隔离，未发布该特性的旧版本不强制依赖。
 
 ## 常见问题
 
diff --git a/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md b/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
index 67504bb98b..c8aaefb185 100644
--- a/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
+++ b/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
@@ -98,16 +98,14 @@ Version `1.7.1` accepts the following configuration names:
 Any other value, including `v2`, `core`, `legacy` or an empty string, falls back to the 10-tool `v1` set in 1.7.1 and logs an error.
 Both toolsets report `mcp_tool_contract_version="2.0"`. This field describes the tool contract, not the package version.
 
-### New Names (Merged to apache/hugegraph-ai main in #382, Not Yet Released)
+### Toolset Naming Evolution {#toolset-evolution}
 
-The default toolset is renamed to `core` and the compatibility toolset to `legacy`.
-This change is merged to apache/hugegraph-ai main in #382, but is not yet in a published release; it **does not apply to the 1.7.1 installation command above**.
-The release version and upgrade command must be updated after publication.
+In upcoming releases, the default toolset is renamed to `core` and the compatibility toolset to `legacy`. For the current `1.7.1` release package, continue using the configurations documented above.
 
-- `v2_core` maps to `core`, and `v1` maps to `legacy`. Old values remain compatibility aliases and emit a migration warning.
-- Inspection reports only `core` or `legacy`. Clients comparing `data.toolset` or `meta.toolset` must update those comparisons.
-- An unset variable selects `core`. Empty or unknown values prevent startup instead of falling back to the compatibility toolset.
-- Toolset selection happens at startup and requires a restart to change. Compatibility mode does not bypass permission checks.
+- `v2_core` maps to `core`, and `v1` maps to `legacy`. Legacy identifiers are retained as backward-compatible aliases with migration warnings.
+- Inspection endpoints report `core` or `legacy`. Clients checking `data.toolset` or `meta.toolset` should update their checks accordingly.
+- An unset variable defaults to `core`. Empty or unrecognized values halt startup rather than silently falling back.
+- Toolset selection is resolved at launch; modifying configuration requires restarting the client. Compatibility mode does not bypass security or read-only controls.
 
 ## Tool Capabilities
 
@@ -196,11 +194,8 @@ Configure `GRAPH_URL` on the AI service to an address reachable from its contain
 Set `GRAPH_NAME` and `GRAPH_SPACE` to match MCP. Do not use the container's `127.0.0.1` to reach the host graph service.
 Changing the MCP address does not reconfigure the AI service target.
 
-**Capability check protocol in #382 (merged to main, not yet in a published release)**:
-The capability check protocol merged in [apache/hugegraph-ai#382](https://github.com/apache/hugegraph-ai/pull/382) requires
-`GET /vid-embeddings/refresh-capabilities` to return `protocol_version=1`, and sends the expected graph and graphspace
-for service-side validation before refreshing. Services lacking this protocol are rejected. This protocol applies to future
-releases and is not required for the published `1.7.1` package.
+**Capability check protocol**:
+The updated protocol requires `GET /vid-embeddings/refresh-capabilities` to return `protocol_version=1`, transmitting the target graph and graphspace for server-side validation before refreshing embeddings. Services without this endpoint will reject refresh requests. This validation protects multi-tenant boundary integrity in future releases.
 
 ## Troubleshooting
 

From 5167043344ec7be079fd14dcedad440df4b4d8fb Mon Sep 17 00:00:00 2001
From: dark <jin@apache.org>
Date: Fri, 30 Oct 2026 05:34:18 +0800
Subject: [PATCH 6/6] docs(mcp): clarify instance matching for embedding
 refresh and token wording

---
 content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md | 9 +++++----
 content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md | 6 ++----
 2 files changed, 7 insertions(+), 8 deletions(-)

diff --git a/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
index 10248161d2..0c84e16622 100644
--- a/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
+++ b/content/cn/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
@@ -183,12 +183,13 @@ stdout 用于 MCP JSON-RPC，不要将额外的 shell 输出写入该通道。
 
 这段内容应合并到前面的 `env` 对象中。生成和抽取可保持只读；向量刷新要求满足以下条件：
 - 客户端配置：`HUGEGRAPH_MCP_READONLY=false`、`HUGEGRAPH_MCP_ADMIN_MODE=true`，且调用时需传入 `confirm=true`。
-- 服务端配置（HugeGraph-LLM）：需设置 `ENABLE_LOGIN=true` 与 `HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true`，配置强 `USER_TOKEN`，
+- 服务端配置（HugeGraph-LLM）：需设置 `ENABLE_LOGIN=true` 与 `HUGEGRAPH_LLM_ENABLE_THIN_WRITES=true`，配置合规的 `USER_TOKEN`，
   并通过 MCP 的 `HUGEGRAPH_AI_TOKEN` 传递有效认证。若服务端未开启写入门禁，刷新请求将被拒绝并返回 `FEATURE_DISABLED`（"Legacy Thin API writes are disabled"）。
 
-如果 MCP 在宿主机运行，而 AI 在容器中运行，二者访问 HugeGraph 的地址可能不同。
-应在 AI 服务侧配置 `GRAPH_URL` 为容器可访问的地址，例如 `http://server:8080`，并设置 `GRAPH_NAME`、`GRAPH_SPACE`
-与 MCP 目标一致；不要让容器通过 `127.0.0.1` 访问宿主机上的图服务。修改 MCP 地址不会修改 AI 服务目标。
+MCP 与 HugeGraph-LLM 必须连接至同一个底层 HugeGraph 实例。能力校验协议仅校验图名与图空间，
+而实际刷新完全由 AI 服务依据其自身的 `GRAPH_URL` 独立执行；修改 MCP 的 `HUGEGRAPH_URL` 并不会改变 AI 服务的数据目标。
+若 MCP 在宿主机运行，而 AI 在容器中运行，二者访问图服务的网络地址可能不同：应在 AI 服务侧配置 `GRAPH_URL` 为容器可访问的地址
+（例如 `http://server:8080`），并确保 `GRAPH_NAME` 与 `GRAPH_SPACE` 与 MCP 目标一致；不要让容器通过 `127.0.0.1` 访问宿主机上的图服务。
 
 **能力校验协议**：
 新版协议要求调用 `GET /vid-embeddings/refresh-capabilities` 返回 `protocol_version=1`，并在刷新前传递预期图名与 graphspace 由服务端进行合法性校验；不支持该协议的服务将被拒绝。该机制用于保障多租户与图空间隔离，未发布该特性的旧版本不强制依赖。
diff --git a/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md b/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
index c8aaefb185..e5471e1d1b 100644
--- a/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
+++ b/content/en/docs/quickstart/hugegraph-ai/hugegraph-mcp.md
@@ -189,10 +189,8 @@ Embedding refresh additionally requires:
   and valid authentication passed via MCP's `HUGEGRAPH_AI_TOKEN`. Without these service-side gates, refresh requests are rejected
   with `FEATURE_DISABLED` ("Legacy Thin API writes are disabled").
 
-If MCP runs on the host and AI runs in a container, they may need different addresses to reach HugeGraph.
-Configure `GRAPH_URL` on the AI service to an address reachable from its container, such as `http://server:8080`.
-Set `GRAPH_NAME` and `GRAPH_SPACE` to match MCP. Do not use the container's `127.0.0.1` to reach the host graph service.
-Changing the MCP address does not reconfigure the AI service target.
+MCP and HugeGraph-LLM must connect to the same underlying HugeGraph instance. The capability check protocol only verifies `graph_name` and `graphspace`, while the actual embedding refresh executes entirely using the AI service's independent `GRAPH_URL`. Modifying MCP's `HUGEGRAPH_URL` does not redirect the AI service's data target.
+If MCP runs on the host and AI runs in a container, they may need different addresses to reach HugeGraph: configure `GRAPH_URL` on the AI service to an address reachable from its container, such as `http://server:8080`, and ensure `GRAPH_NAME` and `GRAPH_SPACE` match MCP. Do not use the container's `127.0.0.1` to reach the host graph service.
 
 **Capability check protocol**:
 The updated protocol requires `GET /vid-embeddings/refresh-capabilities` to return `protocol_version=1`, transmitting the target graph and graphspace for server-side validation before refreshing embeddings. Services without this endpoint will reject refresh requests. This validation protects multi-tenant boundary integrity in future releases.