This is an automated email from the ASF dual-hosted git repository.
terrymanu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere.git
The following commit(s) were added to refs/heads/master by this push:
new 9bf847a50a4 Refine ShardingSphere-MCP user docs (#38789)
9bf847a50a4 is described below
commit 9bf847a50a4c2425f05de20662f2fb39d5c6e27a
Author: Liang Zhang <[email protected]>
AuthorDate: Wed Jun 3 18:16:55 2026 +0800
Refine ShardingSphere-MCP user docs (#38789)
* clarify ShardingSphere-Proxy and direct database connection scenarios
* align capability, deployment, configuration, and troubleshooting docs
* document runtime protection limits and HTTP session attribution
* remove misleading database wording and startup examples
---
.../shardingsphere-mcp/capabilities.cn.md | 42 +++++++++++++---------
.../shardingsphere-mcp/capabilities.en.md | 42 +++++++++++++---------
.../client-integration/_index.cn.md | 7 ++--
.../client-integration/_index.en.md | 7 ++--
.../shardingsphere-mcp/configuration.cn.md | 37 +++++++++++++++----
.../shardingsphere-mcp/configuration.en.md | 37 +++++++++++++++----
.../shardingsphere-mcp/deployment.cn.md | 41 ++++++++++++++-------
.../shardingsphere-mcp/deployment.en.md | 41 ++++++++++++++-------
.../shardingsphere-mcp/developer-appendix.cn.md | 2 +-
.../shardingsphere-mcp/developer-appendix.en.md | 2 +-
.../shardingsphere-mcp/features/encrypt.cn.md | 7 ++--
.../shardingsphere-mcp/features/encrypt.en.md | 7 ++--
.../shardingsphere-mcp/features/mask.cn.md | 9 ++---
.../shardingsphere-mcp/features/mask.en.md | 9 ++---
.../shardingsphere-mcp/troubleshooting.cn.md | 17 +++++++--
.../shardingsphere-mcp/troubleshooting.en.md | 17 +++++++--
16 files changed, 224 insertions(+), 100 deletions(-)
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
index 0c663d571ce..8daf7e4f92d 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.cn.md
@@ -3,7 +3,7 @@ title = "能力清单"
weight = 2
+++
-本页说明用户可以通过自然语言完成的数据库任务，以及连接 ShardingSphere-Proxy 和普通数据库时的使用边界。
+本页说明用户可以通过自然语言完成的数据库任务，以及连接 ShardingSphere-Proxy 和数据库直连时的使用边界。
## 连接目标
@@ -25,9 +25,10 @@ weight = 2
- 依赖 ShardingSphere 规则、算法或规则变更语句的任务只适用于 Proxy 连接。
- 有副作用的任务应先预览或生成计划，审查后再确认执行。
-### 直接连接数据库
+### 数据库直连
-适合把 ShardingSphere-MCP 作为普通数据库的受控访问入口，用于查看元数据、搜索对象和执行受限 SQL。
+数据库直连指 ShardingSphere-MCP 不经过 ShardingSphere-Proxy，直接连接用户提供的 MySQL、PostgreSQL
等数据库服务。
+这种模式适合把 ShardingSphere-MCP 作为已有数据库的受控访问入口，用于查看元数据、搜索对象和执行受限 SQL。
可用任务包括：
@@ -46,29 +47,36 @@ weight = 2
| 任务 | 自然语言示例 | 连接目标 | 用户关注点 |
| --- | --- | --- | --- |
-| 查看可访问的数据库 | “列出当前可以访问的逻辑库。” | Proxy 或普通数据库 | 确认数据库名称是否和配置一致。 |
-| 查看模式或命名空间 | “查看 `<logic-database>` 中有哪些模式。” | Proxy 或普通数据库 | 多模式数据库应先确认目标模式。
|
-| 查看表或视图 | “列出目标模式中的表和视图。” | Proxy 或普通数据库 | Proxy 连接展示的是逻辑对象。 |
-| 查看列信息 | “查看 `<table-name>` 有哪些列，以及列类型是什么。” | Proxy 或普通数据库 | 列类型以连接目标可见元数据为准。
|
-| 查看索引 | “查看 `<table-name>` 的索引。” | Proxy 或普通数据库 | Proxy
连接下索引信息可能不同于底层物理库完整结构。 |
-| 查看序列 | “列出目标模式中的序列。” | Proxy 或普通数据库 | 仅在连接目标支持序列元数据时可用。 |
+| 查看可访问的数据库 | “列出当前可以访问的数据库。” | Proxy 或数据库直连 | 确认数据库名称是否和配置一致。 |
+| 查看模式或命名空间 | “查看 `<database-name>` 中有哪些模式。” | Proxy 或数据库直连 | 多模式数据库应先确认目标模式。 |
+| 查看表或视图 | “列出目标模式中的表和视图。” | Proxy 或数据库直连 | Proxy 连接展示的是逻辑对象。 |
+| 查看列信息 | “查看 `<table-name>` 有哪些列，以及列类型是什么。” | Proxy 或数据库直连 | 列类型以连接目标可见元数据为准。
|
+| 查看索引 | “查看 `<table-name>` 的索引。” | Proxy 或数据库直连 | Proxy
连接下索引信息可能不同于底层物理库完整结构。 |
+| 查看序列 | “列出目标模式中的序列。” | Proxy 或数据库直连 | 仅在连接目标支持序列元数据时可用。 |
## 元数据搜索
| 任务 | 自然语言示例 | 连接目标 | 用户关注点 |
| --- | --- | --- | --- |
-| 按名称搜索对象 | “查找名字包含 `order` 的表。” | Proxy 或普通数据库 | 适合不知道完整对象名时缩小范围。 |
-| 按对象类型搜索 | “查找名字包含 `user` 的表和视图。” | Proxy 或普通数据库 | 可以指定只看表、视图或列等对象。 |
-| 查找后继续查看详情 | “打开刚才找到的 `orders` 表，查看字段和索引。” | Proxy 或普通数据库 |
搜索结果可作为后续自然语言任务的上下文。 |
+| 按名称搜索对象 | “查找名字包含 `order` 的表。” | Proxy 或数据库直连 | 适合不知道完整对象名时缩小范围。 |
+| 按对象类型搜索 | “查找名字包含 `user` 的表和视图。” | Proxy 或数据库直连 | 可以指定只看表、视图或列等对象。 |
+| 查找后继续查看详情 | “打开刚才找到的 `orders` 表，查看字段和索引。” | Proxy 或数据库直连 |
搜索结果可作为后续自然语言任务的上下文。 |
-## 查询与变更预览
+## 查询与普通 SQL 变更
| 任务 | 自然语言示例 | 连接目标 | 用户关注点 |
| --- | --- | --- | --- |
-| 执行查询 | “查询 `orders` 表前 10 行。” | Proxy 或普通数据库 | 适合查看样例数据或验证查询结果。 |
-| 限制返回行数 | “查询 `orders` 表前 100 行，不要返回更多数据。” | Proxy 或普通数据库 | 避免返回过多数据。 |
-| 预览会修改数据或规则的操作 | “预览这条变更，先不要执行。” | Proxy 或普通数据库 | 执行前审查影响范围。 |
-| 确认执行已预览的变更 | “确认执行刚才预览过的变更。” | Proxy 或普通数据库 | 需要确认已审查副作用。 |
+| 执行查询 | “查询 `orders` 表前 10 行。” | Proxy 或数据库直连 | 适合查看样例数据或验证查询结果。 |
+| 限制返回行数 | “查询 `orders` 表前 100 行，不要返回更多数据。” | Proxy 或数据库直连 | 避免返回过多数据。 |
+| 预览普通 SQL 变更 | “预览这条 SQL 变更，先不要执行。” | Proxy 或数据库直连 | 执行前审查影响范围。 |
+| 确认执行已预览的普通 SQL 变更 | “确认执行刚才预览过的 SQL 变更。” | Proxy 或数据库直连 | 需要确认已审查副作用。 |
+
+## 运行时保护限制
+
+- 未指定返回行数时，查询默认最多返回 100 行。
+- 单次查询最多可请求 5000 行；如果结果被截断，应缩小查询条件、减少返回列或降低返回行数。
+- 查询超时可以由任务请求设置，最大值为 300000 毫秒；未指定时使用 Server 默认行为。
+- 单个 MCP 会话有工具调用次数保护；达到限制后，应结束当前会话并重新创建 MCP 会话。
## ShardingSphere 规则变更
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
index 2e52db335f0..081bfb60748 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/capabilities.en.md
@@ -3,7 +3,7 @@ title = "Capability Catalog"
weight = 2
+++
-This page describes the database tasks that users can complete through natural
language, and the usage boundaries when connecting to ShardingSphere-Proxy or a
regular database.
+This page describes the database tasks that users can complete through natural
language, and the usage boundaries when connecting to ShardingSphere-Proxy or
using a direct database connection.
## Connection Targets
@@ -25,9 +25,10 @@ Usage boundaries:
- Tasks that depend on ShardingSphere rules, algorithms, or rule change
statements apply only to Proxy connections.
- Side-effecting tasks should be previewed or planned first, then reviewed
before execution.
-### Connecting Directly to a Database
+### Direct Database Connection
-Use this mode when ShardingSphere-MCP acts as a controlled access entry for a
regular database, including metadata inspection, object search, and restricted
SQL execution.
+A direct database connection means that ShardingSphere-MCP connects to a
user-provided database service such as MySQL or PostgreSQL without going
through ShardingSphere-Proxy.
+Use this mode when ShardingSphere-MCP acts as a controlled access entry for an
existing database, including metadata inspection, object search, and restricted
SQL execution.
Available tasks include:
@@ -46,29 +47,36 @@ Usage boundaries:
| Task | Natural language example | Connection target | User focus |
| --- | --- | --- | --- |
-| List accessible databases | "List the logical databases that can be
accessed." | Proxy or regular database | Confirm that database names match the
configuration. |
-| Inspect schemas or namespaces | "Show schemas in `<logic-database>`." |
Proxy or regular database | For multi-schema databases, confirm the target
schema first. |
-| Inspect tables or views | "List tables and views in `<schema-name>`." |
Proxy or regular database | Proxy connections show logical objects. |
-| Inspect columns | "Show columns and column types for `<table-name>`." |
Proxy or regular database | Column types follow metadata visible from the
connection target. |
-| Inspect indexes | "Show indexes for `<table-name>`." | Proxy or regular
database | With Proxy connections, index information may differ from the full
physical database structure. |
-| Inspect sequences | "List sequences in `<schema-name>`." | Proxy or regular
database | Available only when the connection target exposes sequence metadata.
|
+| List accessible databases | "List the databases that can be accessed." |
Proxy or direct database connection | Confirm that database names match the
configuration. |
+| Inspect schemas or namespaces | "Show schemas in `<database-name>`." | Proxy
or direct database connection | For multi-schema databases, confirm the target
schema first. |
+| Inspect tables or views | "List tables and views in `<schema-name>`." |
Proxy or direct database connection | Proxy connections show logical objects. |
+| Inspect columns | "Show columns and column types for `<table-name>`." |
Proxy or direct database connection | Column types follow metadata visible from
the connection target. |
+| Inspect indexes | "Show indexes for `<table-name>`." | Proxy or direct
database connection | With Proxy connections, index information may differ from
the full physical database structure. |
+| Inspect sequences | "List sequences in `<schema-name>`." | Proxy or direct
database connection | Available only when the connection target exposes
sequence metadata. |
## Metadata Search
| Task | Natural language example | Connection target | User focus |
| --- | --- | --- | --- |
-| Search objects by name | "Find tables whose names contain `order`." | Proxy
or regular database | Useful when the full object name is unknown. |
-| Search by object type | "Find tables and views whose names contain `user`."
| Proxy or regular database | Narrow the search to tables, views, columns, or
other object types. |
-| Continue from search results | "Open the `orders` table found earlier and
show columns and indexes." | Proxy or regular database | Search results can
provide context for follow-up natural-language tasks. |
+| Search objects by name | "Find tables whose names contain `order`." | Proxy
or direct database connection | Useful when the full object name is unknown. |
+| Search by object type | "Find tables and views whose names contain `user`."
| Proxy or direct database connection | Narrow the search to tables, views,
columns, or other object types. |
+| Continue from search results | "Open the `orders` table found earlier and
show columns and indexes." | Proxy or direct database connection | Search
results can provide context for follow-up natural-language tasks. |
-## Queries and Change Preview
+## Queries and Ordinary SQL Changes
| Task | Natural language example | Connection target | User focus |
| --- | --- | --- | --- |
-| Run a query | "Query the first 10 rows from `orders`." | Proxy or regular
database | Use for sample data inspection or query result validation. |
-| Limit returned rows | "Query the first 100 rows from `orders` and do not
return more." | Proxy or regular database | Avoid returning too much data. |
-| Preview an operation that may change data or rules | "Preview this change
without executing it." | Proxy or regular database | Review impact before
execution. |
-| Confirm a previewed change | "Confirm and execute the change that was just
previewed." | Proxy or regular database | Requires confirmation that side
effects were reviewed. |
+| Run a query | "Query the first 10 rows from `orders`." | Proxy or direct
database connection | Use for sample data inspection or query result
validation. |
+| Limit returned rows | "Query the first 100 rows from `orders` and do not
return more." | Proxy or direct database connection | Avoid returning too much
data. |
+| Preview an ordinary SQL change | "Preview this SQL change without executing
it." | Proxy or direct database connection | Review impact before execution. |
+| Confirm a previewed ordinary SQL change | "Confirm and execute the SQL
change that was just previewed." | Proxy or direct database connection |
Requires confirmation that side effects were reviewed. |
+
+## Runtime Protection Limits
+
+- When the returned row count is not specified, a query returns at most 100
rows by default.
+- A single query can request at most 5000 rows. If the result is truncated,
narrow the predicate, reduce the projection, or request fewer rows.
+- A query timeout can be requested by the task, up to 300000 milliseconds.
When omitted, the Server default behavior is used.
+- Each MCP session has a tool-call quota. When the quota is exhausted, close
the current session and create a new MCP session.
## ShardingSphere Rule Changes
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.cn.md
index b27ad2799cd..14b3385f3b6 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.cn.md
@@ -8,10 +8,9 @@ weight = 4
适合使用客户端集成的场景：
-- 在 AI 应用、IDE 插件或 Agent 平台中接入 ShardingSphere。
-- 基于 ShardingSphere 元数据完成查询辅助、结构理解、问题诊断或治理规划。
-- 为团队提供统一的受控数据库访问通路。
-- 为 AI 应用集成 ShardingSphere 元数据、受控 SQL 和规则变更能力。
+- 在 AI 应用、IDE 插件或 Agent 平台中接入 ShardingSphere-MCP。
+- 通过自然语言查看元数据、执行受控 SQL 或规划 ShardingSphere 规则变更。
+- 为团队提供统一的受控数据库访问入口。
可完成的任务和使用边界见[能力清单](../capabilities/)。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.en.md
index 4b28acad2ea..e5ce5e68209 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/_index.en.md
@@ -8,10 +8,9 @@ After configuration, users can inspect metadata, run
controlled SQL queries, or
Use client integration when:
-- An AI application, IDE extension, or agent platform needs to connect to
ShardingSphere.
-- ShardingSphere metadata should be used for query assistance, structure
understanding, diagnostics, or governance planning.
-- A team needs a unified controlled database access path.
-- An AI application needs ShardingSphere metadata, controlled SQL, and rule
change capabilities.
+- An AI application, IDE extension, or agent platform needs to connect to
ShardingSphere-MCP.
+- Users need to inspect metadata, run controlled SQL, or plan ShardingSphere
rule changes through natural language.
+- A team needs a unified controlled database access entry.
See [Capability Catalog](../capabilities/) for supported tasks and usage
boundaries.
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
index 6823c7b54de..7bd2c877ccb 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/configuration.cn.md
@@ -36,6 +36,30 @@ transport:
| `transport.http.port` | HTTP 监听端口，默认值为 `18088`。 |
| `transport.http.endpointPath` | HTTP 端点路径，默认值为 `/mcp`。 |
+### HTTP 会话归属（可选）
+
+如果 ShardingSphere-MCP 部署在受信网关或反向代理后面，可以让网关注入可信请求头，用于把 MCP 会话和外部用户或调用来源关联起来。
+该配置不提供认证或授权；认证、授权和请求头注入仍应由外层网关完成。
+
+```yaml
+transport:
+ type: STREAMABLE_HTTP
+ http:
+ sessionAttributionSource:
+ subjectHeader: X-ShardingSphere-MCP-Subject
+ sourceHeader: X-ShardingSphere-MCP-Source
+ attributeHeaderPrefix: X-ShardingSphere-MCP-Attribute-
+```
+
+| 配置项 | 说明 |
+| --- | --- |
+| `transport.http.sessionAttributionSource` | HTTP 会话归属来源。未配置时不绑定会话归属。 |
+| `transport.http.sessionAttributionSource.subjectHeader` |
表示外部用户、租户或调用主体的请求头名称。 |
+| `transport.http.sessionAttributionSource.sourceHeader` | 表示调用来源的请求头名称。 |
+| `transport.http.sessionAttributionSource.attributeHeaderPrefix` |
自定义归属属性的请求头前缀。 |
+
+只有确认客户端不能直接伪造这些请求头时，才应启用该配置。
+
## 数据库配置
`runtimeDatabases` 定义 MCP Server 可以连接并对外暴露的数据库。
@@ -53,7 +77,7 @@ runtimeDatabases:
| *名称* | *说明* |
| --- | --- |
-| `databaseType` (+) | 连接端点的数据库协议或方言类型，例如 `MySQL` 或 `PostgreSQL`。它影响元数据识别和 SQL
能力判断，不表示连接目标一定是真实数据库或 ShardingSphere-Proxy。 |
+| `databaseType` (+) | 连接端点的数据库协议或方言类型，例如 `MySQL` 或 `PostgreSQL`。它影响元数据识别和 SQL
能力判断，不表示连接目标一定是数据库直连或 ShardingSphere-Proxy。 |
| `jdbcUrl` (+) | MCP Server 连接运行时数据库的 JDBC URL；使用 ShardingSphere 规则能力时应指向
Proxy 逻辑库。 |
| `username` (+) | 连接运行时数据库的用户名，通常是 ShardingSphere-Proxy 逻辑库用户名。 |
| `password` (?) | 连接运行时数据库的密码。 |
@@ -67,8 +91,8 @@ runtimeDatabases:
注意事项：
- 连接 ShardingSphere-Proxy 时，用户看到的是 ShardingSphere 逻辑库，不是底层物理存储单元。
-- 连接真实数据库时，用户看到的是该 JDBC 目标的元数据，不代表 ShardingSphere 规则状态。
-- 模式、表、视图、索引和序列等元数据依赖目标数据库的 JDBC 元数据；Proxy 和真实数据库的可见结果可能不同。
+- 数据库直连时，用户看到的是目标数据库自身的元数据，不代表 ShardingSphere 规则状态。
+- 模式、表、视图、索引和序列等元数据依赖连接目标的 JDBC 元数据；Proxy 和数据库直连的可见结果可能不同。
- 如果目标 JDBC 驱动没有随发行包提供，请把驱动 jar 放入 `plugins/`。
## 连接目标选择
@@ -82,12 +106,13 @@ runtimeDatabases:
此时用户看到的是 Proxy 暴露的逻辑库、逻辑表和逻辑列。
Proxy 可见元数据可能不同于底层物理库的完整结构；涉及物理列、索引或规则变更的计划应先审查再执行。
-### 连接真实数据库
+### 数据库直连
-如果只需要查看普通数据库元数据、搜索对象或执行受控查询，可以连接真实数据库。
+数据库直连指 ShardingSphere-MCP 不经过 ShardingSphere-Proxy，直接连接用户提供的 MySQL、PostgreSQL
等数据库服务。
+如果只需要查看已有数据库的元数据、搜索对象或执行受控查询，可以使用数据库直连。
此时用户看到的是目标数据库自身元数据，不代表 ShardingSphere 规则状态。
-数据加密、数据脱敏等依赖 ShardingSphere 规则的任务不适用于真实数据库连接。
+数据加密、数据脱敏等依赖 ShardingSphere 规则的任务不适用于数据库直连。
不同连接目标支持的自然语言任务见[能力清单](../capabilities/)。
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/configuration.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/configuration.en.md
index d04eaf93b2f..33777da2961 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/configuration.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/configuration.en.md
@@ -36,6 +36,30 @@ transport:
| `transport.http.port` | HTTP bind port. The default value is `18088`. |
| `transport.http.endpointPath` | HTTP endpoint path. The default value is
`/mcp`. |
+### HTTP Session Attribution (Optional)
+
+When ShardingSphere-MCP runs behind a trusted gateway or reverse proxy, the
gateway can inject trusted headers to associate an MCP session with an external
user or request source.
+This configuration does not provide authentication or authorization.
Authentication, authorization, and header injection should still be handled by
the outer gateway.
+
+```yaml
+transport:
+ type: STREAMABLE_HTTP
+ http:
+ sessionAttributionSource:
+ subjectHeader: X-ShardingSphere-MCP-Subject
+ sourceHeader: X-ShardingSphere-MCP-Source
+ attributeHeaderPrefix: X-ShardingSphere-MCP-Attribute-
+```
+
+| Configuration item | Description |
+| --- | --- |
+| `transport.http.sessionAttributionSource` | HTTP session attribution source.
When omitted, session attribution is not bound. |
+| `transport.http.sessionAttributionSource.subjectHeader` | Header name for
the external user, tenant, or request subject. |
+| `transport.http.sessionAttributionSource.sourceHeader` | Header name for the
request source. |
+| `transport.http.sessionAttributionSource.attributeHeaderPrefix` | Header
prefix for custom attribution attributes. |
+
+Enable this only when clients cannot forge these headers directly.
+
## Database configuration
`runtimeDatabases` defines the databases that the MCP Server can connect to
and expose to users.
@@ -53,7 +77,7 @@ runtimeDatabases:
| *Name* | *Description* |
| --- | --- |
-| `databaseType` (+) | Database protocol or dialect type of the connection
endpoint, such as `MySQL` or `PostgreSQL`. It affects metadata recognition and
SQL capability judgment; it does not mean the endpoint is necessarily a
physical database or ShardingSphere-Proxy. |
+| `databaseType` (+) | Database protocol or dialect type of the connection
endpoint, such as `MySQL` or `PostgreSQL`. It affects metadata recognition and
SQL capability judgment; it does not mean the endpoint is necessarily a direct
database connection or ShardingSphere-Proxy. |
| `jdbcUrl` (+) | JDBC URL used by the MCP Server to connect to the runtime
database. Point it to a Proxy logical database when using ShardingSphere rule
capabilities. |
| `username` (+) | Username for the runtime database, usually the
ShardingSphere-Proxy logical database username. |
| `password` (?) | Password for the runtime database. |
@@ -67,8 +91,8 @@ Legend:
Notes:
- When the target is ShardingSphere-Proxy, users see ShardingSphere logical
databases, not physical storage units.
-- When the target is a physical database, users see metadata from that JDBC
target, not ShardingSphere rule state.
-- Schema, table, view, index, and sequence metadata depends on target JDBC
metadata. Proxy-visible metadata and physical database metadata may differ.
+- With a direct database connection, users see metadata from the target
database itself, not ShardingSphere rule state.
+- Schema, table, view, index, and sequence metadata depends on JDBC metadata
from the connection target. Proxy-visible metadata and direct-connection
metadata may differ.
- If the target JDBC driver is not packaged, copy the driver jar under
`plugins/`.
## Choose a Connection Target
@@ -82,12 +106,13 @@ Connect to a ShardingSphere-Proxy logical database when
ShardingSphere rule stat
Users see the logical databases, tables, and columns exposed by Proxy.
Proxy-visible metadata may differ from the complete physical database
structure. Plans involving physical columns, indexes, or rule changes should be
reviewed before execution.
-### Connecting to a physical database
+### Direct database connection
-Connect directly to a physical database when only ordinary metadata
inspection, object search, or controlled queries are needed.
+A direct database connection means that ShardingSphere-MCP connects to a
user-provided database service such as MySQL or PostgreSQL without going
through ShardingSphere-Proxy.
+Use it when only metadata inspection, object search, or controlled queries
against an existing database are needed.
Users see metadata from the target database itself, not ShardingSphere rule
state.
-Tasks that depend on ShardingSphere rules, such as data encryption and data
masking, do not apply to direct physical database connections.
+Tasks that depend on ShardingSphere rules, such as data encryption and data
masking, do not apply to direct database connections.
For natural-language tasks supported by each connection target, see
[Capability Catalog](../capabilities/).
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/deployment.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/deployment.cn.md
index 0889b052b18..751dd7e6922 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/deployment.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/deployment.cn.md
@@ -31,26 +31,42 @@ OCI image 形态是：
ghcr.io/apache/shardingsphere-mcp:<version>
```
-以 HTTP 模式运行：
-
-```bash
-docker run --rm -p 18088:18088
ghcr.io/apache/shardingsphere-mcp:${latest.release.version}
+使用 OCI 镜像前，应先准备自定义配置文件。
+HTTP 模式在容器中运行时，`bindHost` 应绑定到容器可暴露的网络接口，例如 `0.0.0.0`：
+
+```yaml
+transport:
+ type: STREAMABLE_HTTP
+ http:
+ bindHost: 0.0.0.0
+ port: 18088
+ endpointPath: /mcp
+
+runtimeDatabases:
+ "<logic-database>":
+ databaseType: MySQL
+ jdbcUrl: "jdbc:mysql://<proxy-host>:<proxy-port>/<logic-database>"
+ username: "<proxy-username>"
+ password: "<proxy-password>"
+ driverClassName: "com.mysql.cj.jdbc.Driver"
```
-以 STDIO 模式运行：
+以 HTTP 模式运行，并挂载自定义配置文件和插件目录：
```bash
-docker run --rm -i \
- -e SHARDINGSPHERE_MCP_TRANSPORT=stdio \
+docker run --rm -p 18088:18088 \
+ -e
SHARDINGSPHERE_MCP_CONFIG=/opt/shardingsphere-mcp/conf/custom-mcp-http.yaml \
+ -v
/path/to/mcp-http.yaml:/opt/shardingsphere-mcp/conf/custom-mcp-http.yaml:ro \
+ -v /path/to/plugins:/opt/shardingsphere-mcp/plugins:ro \
ghcr.io/apache/shardingsphere-mcp:${latest.release.version}
```
-使用自定义配置文件：
+以 STDIO 模式运行时，配置文件中的 `transport.type` 应为 `STDIO`：
```bash
-docker run --rm -p 18088:18088 \
- -e
SHARDINGSPHERE_MCP_CONFIG=/opt/shardingsphere-mcp/conf/custom-mcp-http.yaml \
- -v
/path/to/mcp-http.yaml:/opt/shardingsphere-mcp/conf/custom-mcp-http.yaml:ro \
+docker run --rm -i \
+ -e
SHARDINGSPHERE_MCP_CONFIG=/opt/shardingsphere-mcp/conf/custom-mcp-stdio.yaml \
+ -v
/path/to/mcp-stdio.yaml:/opt/shardingsphere-mcp/conf/custom-mcp-stdio.yaml:ro \
-v /path/to/plugins:/opt/shardingsphere-mcp/plugins:ro \
ghcr.io/apache/shardingsphere-mcp:${latest.release.version}
```
@@ -58,7 +74,7 @@ docker run --rm -p 18088:18088 \
根据目标能力边界配置 `runtimeDatabases`：
- 使用 ShardingSphere 规则能力或规则变更流程时，指向用户已准备好的 ShardingSphere-Proxy 逻辑库。
-- 仅使用通用 JDBC 元数据、元数据搜索和受控 SQL 能力时，可以指向任意可连接的 JDBC 数据库。
+- 仅使用元数据搜索、元数据查看和受控 SQL 能力时，可以使用数据库直连。
## 安全部署建议
@@ -76,6 +92,7 @@ HTTP 绑定建议：
- 本地调试使用 `127.0.0.1`。
- 容器或内网部署使用受控网络接口。
- 面向远程客户端暴露时，避免直接裸露 MCP Server。
+- 需要把会话和外部用户或调用来源关联时，由受信网关注入会话归属请求头；不要允许客户端直接伪造这些请求头。
## 日志
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/deployment.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/deployment.en.md
index a410c4d32a5..a8aaa3662ec 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/deployment.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/deployment.en.md
@@ -31,26 +31,42 @@ The OCI image shape is:
ghcr.io/apache/shardingsphere-mcp:<version>
```
-Run in HTTP mode:
-
-```bash
-docker run --rm -p 18088:18088
ghcr.io/apache/shardingsphere-mcp:${latest.release.version}
+Before using the OCI image, prepare a custom configuration file.
+When HTTP mode runs in a container, `bindHost` should bind to a network
interface that the container can expose, such as `0.0.0.0`:
+
+```yaml
+transport:
+ type: STREAMABLE_HTTP
+ http:
+ bindHost: 0.0.0.0
+ port: 18088
+ endpointPath: /mcp
+
+runtimeDatabases:
+ "<logic-database>":
+ databaseType: MySQL
+ jdbcUrl: "jdbc:mysql://<proxy-host>:<proxy-port>/<logic-database>"
+ username: "<proxy-username>"
+ password: "<proxy-password>"
+ driverClassName: "com.mysql.cj.jdbc.Driver"
```
-Run in STDIO mode:
+Run in HTTP mode with a custom configuration file and plugin directory:
```bash
-docker run --rm -i \
- -e SHARDINGSPHERE_MCP_TRANSPORT=stdio \
+docker run --rm -p 18088:18088 \
+ -e
SHARDINGSPHERE_MCP_CONFIG=/opt/shardingsphere-mcp/conf/custom-mcp-http.yaml \
+ -v
/path/to/mcp-http.yaml:/opt/shardingsphere-mcp/conf/custom-mcp-http.yaml:ro \
+ -v /path/to/plugins:/opt/shardingsphere-mcp/plugins:ro \
ghcr.io/apache/shardingsphere-mcp:${latest.release.version}
```
-Use a custom configuration file:
+When running in STDIO mode, set `transport.type` in the configuration file to
`STDIO`:
```bash
-docker run --rm -p 18088:18088 \
- -e
SHARDINGSPHERE_MCP_CONFIG=/opt/shardingsphere-mcp/conf/custom-mcp-http.yaml \
- -v
/path/to/mcp-http.yaml:/opt/shardingsphere-mcp/conf/custom-mcp-http.yaml:ro \
+docker run --rm -i \
+ -e
SHARDINGSPHERE_MCP_CONFIG=/opt/shardingsphere-mcp/conf/custom-mcp-stdio.yaml \
+ -v
/path/to/mcp-stdio.yaml:/opt/shardingsphere-mcp/conf/custom-mcp-stdio.yaml:ro \
-v /path/to/plugins:/opt/shardingsphere-mcp/plugins:ro \
ghcr.io/apache/shardingsphere-mcp:${latest.release.version}
```
@@ -58,7 +74,7 @@ docker run --rm -p 18088:18088 \
Configure `runtimeDatabases` according to the target capability boundary:
- Point it to a ShardingSphere-Proxy logical database when using
ShardingSphere rule capabilities or the rule change flow.
-- Point it to any reachable JDBC database only for general JDBC metadata,
metadata search, and controlled SQL capabilities.
+- Use a direct database connection only for metadata search, metadata
inspection, and controlled SQL capabilities.
## Secure deployment
@@ -76,6 +92,7 @@ HTTP binding recommendations:
- Use `127.0.0.1` for local debugging.
- Use a controlled network interface for container or intranet deployments.
- Avoid exposing the MCP Server directly to remote clients.
+- When sessions must be associated with external users or request sources, let
a trusted gateway inject session attribution headers. Do not allow clients to
forge these headers directly.
## Logs
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.cn.md
index fb0b890fa55..eeb26b436d1 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.cn.md
@@ -4,7 +4,7 @@ weight = 9
+++
本页面面向需要自研 MCP 集成、调试协议请求或定位客户端适配问题的开发者。
-普通用户通常不需要阅读本页，可直接参考[快速开始](../quick-start/)、[客户端集成](../client-integration/)和[能力清单](../capabilities/)。
+常规使用可直接参考[快速开始](../quick-start/)、[客户端集成](../client-integration/)和[能力清单](../capabilities/)。
## 通用客户端配置示例
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.en.md
index b6ca1fd0573..f990f69ad43 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/developer-appendix.en.md
@@ -4,7 +4,7 @@ weight = 9
+++
This page is for developers who build custom MCP integrations, debug protocol
requests, or troubleshoot client adaptation issues.
-Most users do not need this page. Use [Quick Start](../quick-start/), [Client
Integration](../client-integration/), and [Capability
Catalog](../capabilities/) for normal usage.
+For normal usage, see [Quick Start](../quick-start/), [Client
Integration](../client-integration/), and [Capability
Catalog](../capabilities/).
## Generic Client Configuration Examples
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/encrypt.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/encrypt.cn.md
index 630d94b026c..32431aa1b92 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/features/encrypt.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/features/encrypt.cn.md
@@ -10,7 +10,7 @@ weight = 2
- 当前版本只支持连接 ShardingSphere-Proxy 暴露的逻辑库。
- `runtimeDatabases` 应指向 Proxy 逻辑库，而不是底层物理存储库。
-- 直连真实数据库时，本功能不适用；真实数据库通常不识别 ShardingSphere 加密规则变更语句，也不能暴露 Proxy
中可见的加密算法插件和规则状态。
+- 数据库直连时，本功能不适用；目标数据库通常不识别 ShardingSphere 加密规则变更语句，也不能暴露 Proxy 中可见的加密算法插件和规则状态。
- 目标逻辑表和逻辑列应能通过 Proxy 暴露的 JDBC 元数据发现；这些信息不保证等同于底层物理库的完整元数据。
## 通过自然语言使用
@@ -20,6 +20,7 @@ weight = 2
示例：
- 检查 `<logic-database>.orders.status` 当前是否已有加密规则。
+- 列出当前 Proxy 可用的数据加密算法。
- 为 `<logic-database>.orders.status` 规划可逆加密，需要支持等值查询，先预览不要执行。
- 使用 AES 算法继续刚才的计划，密钥通过受保护渠道提供。
- 确认并执行刚才的加密规则计划，然后校验结果。
@@ -36,7 +37,7 @@ weight = 2
| 模式或命名空间 | 多模式逻辑库建议说明。 | “模式是 `public`。” |
| 操作类型 | 创建、修改或删除加密规则。 | “新增加密规则”或“删除这个列的加密规则”。 |
| 加密目标 | 说明是否需要可逆加密、等值查询或模糊查询。 | “需要可逆加密，并支持等值查询。” |
-| 算法偏好 | 可以指定算法，也可以要求 MCP 根据可用算法推荐。 | “优先使用 AES。” |
+| 算法偏好 | 可以指定算法，也可以要求 MCP 根据 Proxy 可用算法推荐。 | “列出当前 Proxy 可用的数据加密算法。”或“优先使用
AES。” |
| 算法参数 | 例如密钥等敏感参数，应通过受保护渠道提供。 | “密钥通过受保护渠道提供。” |
| 索引建议 | 是否允许为辅助查询列生成物理索引建议。 | “允许生成等值查询辅助列的索引建议。” |
@@ -86,7 +87,7 @@ weight = 2
### 支持范围
- 仅支持 ShardingSphere-Proxy 逻辑库。
-- 直连真实数据库时，本功能不适用。
+- 数据库直连时，本功能不适用。
### 能力边界
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/encrypt.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/encrypt.en.md
index 3afe8d74619..f8e6f10e437 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/features/encrypt.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/features/encrypt.en.md
@@ -10,7 +10,7 @@ Actual encryption capability is provided by
ShardingSphere-Proxy and its encrypt
- The current version supports logical databases exposed by
ShardingSphere-Proxy only.
- `runtimeDatabases` should point to Proxy logical databases, not physical
storage databases.
-- This feature does not apply to direct physical database connections. A
physical database usually does not understand ShardingSphere encryption rule
change statements and cannot expose Proxy-visible encryption algorithm plugins
or rule state.
+- This feature does not apply to direct database connections. The target
database usually does not understand ShardingSphere encryption rule change
statements and cannot expose Proxy-visible encryption algorithm plugins or rule
state.
- The target logical table and column should be discoverable through JDBC
metadata exposed by Proxy. This metadata should not be treated as a complete
physical database catalog.
## Use through natural language
@@ -20,6 +20,7 @@ Users describe the encryption goal in an AI application that
integrates Sharding
Examples:
- Check whether `<logic-database>.orders.status` already has an encryption
rule.
+- List data encryption algorithms available from the current Proxy.
- Plan reversible encryption for `<logic-database>.orders.status` with
equality query support, and preview it without execution.
- Continue the previous plan with the AES algorithm and provide the key
through a protected channel.
- Confirm and execute the previous encryption rule plan, then validate the
result.
@@ -36,7 +37,7 @@ When using natural language, include the following
information when possible:
| Schema or namespace | Recommended for multi-schema logical databases. | "The
schema is `public`." |
| Operation type | Create, alter, or drop an encryption rule. | "Create an
encryption rule" or "drop the encryption rule for this column." |
| Encryption goal | Describe whether reversible encryption, equality query, or
LIKE query is required. | "Use reversible encryption and support equality
queries." |
-| Algorithm preference | Specify an algorithm, or let MCP recommend one from
available algorithms. | "Prefer AES." |
+| Algorithm preference | Specify an algorithm, or let MCP recommend one from
algorithms available from Proxy. | "List data encryption algorithms available
from the current Proxy." or "Prefer AES." |
| Algorithm properties | Sensitive values such as keys should be supplied
through protected channels. | "The key is supplied through a protected
channel." |
| Index suggestions | Whether physical index suggestions for assisted query
columns are allowed. | "Allow index suggestions for the assisted query column."
|
@@ -86,7 +87,7 @@ For the general review flow of rule changes, see [Rule Change
Flow](../plugin-wo
### Supported scope
- Supports ShardingSphere-Proxy logical databases only.
-- This feature does not apply to direct physical database connections.
+- This feature does not apply to direct database connections.
### Capability boundaries
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/mask.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/mask.cn.md
index 612ffdf8d6f..5f7c78df0b4 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/features/mask.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/features/mask.cn.md
@@ -10,7 +10,7 @@ weight = 3
- 当前版本只支持连接 ShardingSphere-Proxy 暴露的逻辑库。
- `runtimeDatabases` 应指向 Proxy 逻辑库，而不是底层物理存储库。
-- 直连真实数据库时，本功能不适用；真实数据库通常不识别 ShardingSphere 脱敏规则变更语句，也不能暴露 Proxy
中可见的脱敏算法插件和规则状态。
+- 数据库直连时，本功能不适用；目标数据库通常不识别 ShardingSphere 脱敏规则变更语句，也不能暴露 Proxy 中可见的脱敏算法插件和规则状态。
- 目标逻辑表和逻辑列应能通过 Proxy 暴露的 JDBC 元数据发现；这些信息不保证等同于底层物理库的完整元数据。
## 通过自然语言使用
@@ -20,6 +20,7 @@ weight = 3
示例：
- 检查 `<logic-database>.orders.phone` 当前是否已有脱敏规则。
+- 列出当前 Proxy 可用的数据脱敏算法。
- 为 `<logic-database>.orders.phone` 规划手机号脱敏，保留前 3 后 4，先预览不要执行。
- 调整刚才的计划，把替换字符改成 `*`。
- 确认并执行刚才的脱敏规则计划，然后校验结果。
@@ -36,7 +37,7 @@ weight = 3
| 模式或命名空间 | 多模式逻辑库建议说明。 | “模式是 `public`。” |
| 操作类型 | 创建、修改或删除脱敏规则。 | “新增脱敏规则”或“删除这个列的脱敏规则”。 |
| 脱敏目标 | 说明保留位数、替换字符或其他脱敏效果。 | “手机号保留前 3 后 4，中间用 `*` 替换。” |
-| 算法偏好 | 可以指定算法，也可以要求 MCP 根据可用算法推荐。 | “优先使用 keep-first-n-last-m 算法。” |
+| 算法偏好 | 可以指定算法，也可以要求 MCP 根据 Proxy 可用算法推荐。 | “列出当前 Proxy 可用的数据脱敏算法。”或“优先使用
keep-first-n-last-m 算法。” |
| 算法参数 | 例如保留位数和替换字符。 | “保留前 3 后 4，替换字符是 `*`。” |
## 创建、修改和删除规则
@@ -74,7 +75,7 @@ weight = 3
### 支持范围
- 仅支持 ShardingSphere-Proxy 逻辑库。
-- 直连真实数据库时，本功能不适用。
+- 数据库直连时，本功能不适用。
### 能力边界
@@ -85,7 +86,7 @@ weight = 3
### 元数据边界
- 逻辑列和规则校验以 Proxy 可见信息为准。
-- 直连真实数据库只能执行普通 SQL，不代表脱敏规则状态。
+- 数据库直连只能执行普通 SQL，不代表脱敏规则状态。
### 对象名处理边界
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/features/mask.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/features/mask.en.md
index 45e14971909..57c321a1c39 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/features/mask.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/features/mask.en.md
@@ -10,7 +10,7 @@ Mask rules apply directly to logical columns and do not
generate physical derive
- The current version supports logical databases exposed by
ShardingSphere-Proxy only.
- `runtimeDatabases` should point to Proxy logical databases, not physical
storage databases.
-- This feature does not apply to direct physical database connections. A
physical database usually does not understand ShardingSphere masking rule
change statements and cannot expose Proxy-visible masking algorithm plugins or
rule state.
+- This feature does not apply to direct database connections. The target
database usually does not understand ShardingSphere masking rule change
statements and cannot expose Proxy-visible masking algorithm plugins or rule
state.
- The target logical table and column should be discoverable through JDBC
metadata exposed by Proxy. This metadata should not be treated as a complete
physical database catalog.
## Use through natural language
@@ -20,6 +20,7 @@ Users describe the masking goal in an AI application that
integrates ShardingSph
Examples:
- Check whether `<logic-database>.orders.phone` already has a masking rule.
+- List data masking algorithms available from the current Proxy.
- Plan phone-number masking for `<logic-database>.orders.phone`, keep the
first 3 and last 4 characters, and preview it without execution.
- Adjust the previous plan to use `*` as the replacement character.
- Confirm and execute the previous masking rule plan, then validate the result.
@@ -36,7 +37,7 @@ When using natural language, include the following
information when possible:
| Schema or namespace | Recommended for multi-schema logical databases. | "The
schema is `public`." |
| Operation type | Create, alter, or drop a masking rule. | "Create a masking
rule" or "drop the masking rule for this column." |
| Masking goal | Describe retained characters, replacement characters, or
other masking effects. | "Keep the first 3 and last 4 phone-number characters,
and replace the middle part with `*`." |
-| Algorithm preference | Specify an algorithm, or let MCP recommend one from
available algorithms. | "Prefer the keep-first-n-last-m algorithm." |
+| Algorithm preference | Specify an algorithm, or let MCP recommend one from
algorithms available from Proxy. | "List data masking algorithms available from
the current Proxy." or "Prefer the keep-first-n-last-m algorithm." |
| Algorithm properties | Provide retained character counts and replacement
characters. | "Keep the first 3 and last 4 characters, and use `*` as the
replacement character." |
## Create, alter, and drop rules
@@ -74,7 +75,7 @@ For the general review flow of rule changes, see [Rule Change
Flow](../plugin-wo
### Supported scope
- Supports ShardingSphere-Proxy logical databases only.
-- This feature does not apply to direct physical database connections.
+- This feature does not apply to direct database connections.
### Capability boundaries
@@ -85,7 +86,7 @@ For the general review flow of rule changes, see [Rule Change
Flow](../plugin-wo
### Metadata boundaries
- Logical column and rule validation are based on what Proxy exposes.
-- Direct physical database connections can execute ordinary SQL only and do
not represent masking rule state.
+- Direct database connections can execute ordinary SQL only and do not
represent masking rule state.
### Identifier handling boundaries
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
index bac3c79d903..6f115b273f5 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
@@ -12,12 +12,15 @@ weight = 7
| --- | --- | --- |
| MCP Server 启动失败 | JDK、配置路径、YAML 字段或必填字段不正确。 | 查看启动终端和
`logs/mcp.log`，确认配置文件路径和必填字段。 |
| AI 应用无法连接 ShardingSphere-MCP | 端口、端点路径、传输方式、绑定地址或客户端配置不正确。 | 检查
`port`、`endpointPath`、`bindHost` 和 AI 应用中的 MCP Server 地址。 |
-| 远程访问 HTTP 服务失败 | HTTP 绑定地址、安全策略或网关配置不正确。 |
本机调试用回环地址；远程访问放在受控网关或反向代理后面；详细原因看服务端日志。 |
+| 远程访问 HTTP 服务失败 | HTTP 绑定地址、安全策略、Origin 请求头或网关配置不正确。 |
本机调试用回环地址；远程访问放在受控网关或反向代理后面；详细原因看服务端日志。 |
+| HTTP 请求被拒绝 | 请求携带的 Origin 请求头不符合 HTTP 传输安全策略，或同一 MCP 会话中的可信归属请求头不一致。 | 检查
`bindHost`、客户端访问方式、网关请求头转发策略和会话归属配置。 |
| STDIO 模式没有响应 | 用户直接把 STDIO 当成命令行交互入口，或 AI 应用没有正确拉起进程。 | 由 AI 应用拉起
ShardingSphere-MCP；诊断信息看 stderr 或 `logs/mcp.log`。 |
| 看不到逻辑库 | 未配置逻辑库、逻辑库名称不正确、连接失败、权限不足，或目标范围确实为空。 | 确认
`runtimeDatabases`、逻辑库名称、连接错误分类和账号权限。 |
-| 查不到表、列或索引 | 连接目标不同、模式不正确、账号权限不足，或 Proxy 暴露的逻辑元数据与底层物理库不同。 | 先确认连接的是
ShardingSphere-Proxy 还是普通数据库，再检查模式、账号权限和 Proxy 可见元数据。 |
+| 查不到表、列或索引 | 连接目标不同、模式不正确、账号权限不足，或 Proxy 暴露的逻辑元数据与底层物理库不同。 | 先确认连接的是
ShardingSphere-Proxy 还是数据库直连，再检查模式、账号权限和 Proxy 可见元数据。 |
| JDBC 驱动错误 | 驱动不在类路径，或 `driverClassName` 不正确。 | 把驱动 jar 放入 `plugins/`，并确认
`driverClassName` 非空且类名正确。 |
-| 只读查询失败 | SQL 语法、目标表名、模式、权限或返回行数限制不正确。 | 先让 AI 应用查看表结构，再执行只读查询，并限制返回行数。 |
+| 只读查询失败 | SQL 语法、目标表名、模式、权限、返回行数或超时限制不正确。 | 先让 AI 应用查看表结构，再执行只读查询，并限制返回行数。 |
+| 查询结果被截断 | 查询结果超过返回行数限制。 | 缩小查询条件、减少返回列或降低返回行数。 |
+| 当前会话无法继续调用工具 | MCP 会话达到工具调用次数保护限制。 | 结束当前会话并重新创建 MCP 会话。 |
| 有副作用 SQL 无法执行 | SQL 类型有副作用，或未先预览和确认。 | 先要求预览变更 SQL，审查影响范围后再确认执行。 |
| 加密或脱敏计划无法生成 | 连接目标不是 Proxy、目标列不可见、算法不可用，或缺少必要参数。 | 确认 `runtimeDatabases` 指向
Proxy 逻辑库，并补充逻辑库、表、列、算法和参数。 |
| 规则变更执行后校验不通过 | 规则未成功执行、权限不足、元数据未刷新，或人工执行包未完成执行。 |
查看规则变更计划、执行结果和日志；人工执行后再发起校验。 |
@@ -26,6 +29,7 @@ weight = 7
补充说明：
- `username` 和 `driverClassName` 必须显式写出且不能为空；无密码账号可以省略 `password` 或写 `""`。
+- 查询默认最多返回 100 行，单次查询最多可请求 5000 行；查询超时最大可请求 300000 毫秒。
- 人工执行包中的密钥占位符应由执行人员在受控环境替换。
- 开发者需要排查协议请求时，可参考[自研集成附录](../developer-appendix/)。
@@ -44,11 +48,18 @@ weight = 7
| `connection_failed` | 连接失败，但无法归类为更具体的原因。 |
| `database_not_visible` | 指定逻辑库对当前连接不可见。 |
+## 运行时保护分类
+
+| 分类 | 含义 |
+| --- | --- |
+| `tool_call_limit_exceeded` | 当前 MCP 会话达到工具调用次数保护限制。 |
+
## 查询与变更建议
| 场景 | 建议 |
| --- | --- |
| 查询数据 | 建议限制返回行数。 |
+| 查询结果被截断 | 缩小查询条件、减少返回列或降低返回行数。 |
| 分析 SQL 执行计划 | 仅在目标逻辑库能力允许时使用。 |
| 修改数据、结构、规则或事务状态 | 先预览并审查副作用，再决定是否执行。 |
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
index 64188cadeb7..3d070bc7865 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
@@ -12,12 +12,15 @@ For feature-specific business rule issues, see the
corresponding feature plugin
| --- | --- | --- |
| MCP Server startup failure | JDK, config path, YAML field, or required field
is wrong. | Inspect the startup terminal and `logs/mcp.log`; confirm the
configuration file path and required fields. |
| The AI application cannot connect to ShardingSphere-MCP | Port, endpoint
path, transport type, bind address, or client configuration is wrong. | Check
`port`, `endpointPath`, `bindHost`, and the MCP Server address configured in
the AI application. |
-| Remote HTTP access fails | HTTP bind address, security policy, or gateway
configuration is wrong. | Use loopback locally; place remote access behind a
controlled gateway or reverse proxy; inspect server logs for details. |
+| Remote HTTP access fails | HTTP bind address, security policy, Origin
header, or gateway configuration is wrong. | Use loopback locally; place remote
access behind a controlled gateway or reverse proxy; inspect server logs for
details. |
+| HTTP request is rejected | The request carries an Origin header that does
not satisfy the HTTP transport security policy, or trusted attribution headers
are inconsistent within the same MCP session. | Check `bindHost`, client access
mode, gateway header forwarding, and session attribution configuration. |
| No response in STDIO mode | STDIO is used as an interactive command-line
entry, or the AI application does not launch the process correctly. | Let the
AI application launch ShardingSphere-MCP; inspect stderr or `logs/mcp.log` for
diagnostics. |
| Logical databases are not visible | No logical database is configured, the
logical database name is wrong, connection failed, permission is insufficient,
or the target scope is empty. | Verify `runtimeDatabases`, logical database
names, connection failure category, and account privileges. |
-| Tables, columns, or indexes cannot be found | The connection target is
different, schema is wrong, account privileges are insufficient, or
Proxy-visible logical metadata differs from the physical database. | Confirm
whether the target is ShardingSphere-Proxy or a regular database, then check
schema, account privileges, and Proxy-visible metadata. |
+| Tables, columns, or indexes cannot be found | The connection target is
different, schema is wrong, account privileges are insufficient, or
Proxy-visible logical metadata differs from the underlying physical database. |
Confirm whether the target is ShardingSphere-Proxy or a direct database
connection, then check schema, account privileges, and Proxy-visible metadata. |
| JDBC driver error | Driver is not on the classpath, or `driverClassName` is
wrong. | Put the driver jar under `plugins/`, and keep `driverClassName`
non-empty and correct. |
-| Read-only query fails | SQL syntax, target table name, schema, privilege, or
row limit is wrong. | Ask the AI application to inspect table structure first,
then run a read-only query with a row limit. |
+| Read-only query fails | SQL syntax, target table name, schema, privilege,
row limit, or timeout limit is wrong. | Ask the AI application to inspect table
structure first, then run a read-only query with a row limit. |
+| Query result is truncated | The query result exceeds the returned row limit.
| Narrow the predicate, reduce the projection, or request fewer rows. |
+| Current session cannot continue calling tools | The MCP session has reached
the tool-call protection limit. | Close the current session and create a new
MCP session. |
| Side-effecting SQL cannot be executed | The SQL has side effects, or it was
not previewed and confirmed first. | Preview the change SQL first, review the
impact, then confirm execution. |
| Encryption or masking plan cannot be generated | The target is not Proxy,
the target column is not visible, the algorithm is unavailable, or required
parameters are missing. | Ensure that `runtimeDatabases` points to a Proxy
logical database, then provide logical database, table, column, algorithm, and
parameters. |
| Validation fails after a rule change | The rule was not applied
successfully, permission is insufficient, metadata is not refreshed, or a
manual package was not executed. | Inspect the rule change plan, execution
result, and logs; validate again after manual execution is completed. |
@@ -26,6 +29,7 @@ For feature-specific business rule issues, see the
corresponding feature plugin
Additional notes:
- `username` and `driverClassName` must be declared explicitly and cannot be
empty; a no-password account can omit `password` or use `""`.
+- Queries return at most 100 rows by default. A single query can request at
most 5000 rows, and the maximum requested query timeout is 300000 milliseconds.
- Secret placeholders in manual packages should be replaced by operators in a
controlled environment.
- For protocol request debugging, see the [Custom Integration
Appendix](../developer-appendix/).
@@ -44,11 +48,18 @@ When a runtime database or ShardingSphere-Proxy connection
fails, MCP responses
| `connection_failed` | The connection failed, but cannot be classified into a
more specific cause. |
| `database_not_visible` | The specified logical database is not visible to
the current connection. |
+## Runtime Protection Categories
+
+| Category | Meaning |
+| --- | --- |
+| `tool_call_limit_exceeded` | The current MCP session has reached the
tool-call protection limit. |
+
## Query and Change Recommendations
| Scenario | Recommendation |
| --- | --- |
| Query data | Limit returned rows. |
+| Truncated query result | Narrow the predicate, reduce the projection, or
request fewer rows. |
| Analyze an SQL execution plan | Use only when the target logical database
capability allows it. |
| Change data, structure, rules, or transaction state | Preview and review
side effects before deciding whether to execute. |
