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 6dd43c31873 Add MCP platform integration guides (#38804)
6dd43c31873 is described below
commit 6dd43c31873c6d1fb15cc1b2ab575e5673702def
Author: Liang Zhang <[email protected]>
AuthorDate: Thu Jun 4 19:08:40 2026 +0800
Add MCP platform integration guides (#38804)
* Make required checks optional
Temporarily comment out the master branch required status check contexts
for Checkstyle, Spotless, and License because GitHub Actions runner capacity is
insufficient and required checks take too long to finish.
The workflow jobs are kept so the checks still run as ordinary PR checks.
* Add MCP platform integration guides
Add OpenAI Responses API, ChatGPT Developer Mode, and
Anthropic MCP Connector integration guides, and align the
existing Codex and Claude Code pages to a shared template.
Reorganize the client integration index into client and
platform/API entry points, clarify local-vs-remote MCP
boundaries, standardize verification steps, and add focused
troubleshooting guidance for platform integrations.
* Add MCP platform integration guides
Add OpenAI Responses API, ChatGPT Developer Mode, and
Anthropic MCP Connector integration guides, and align the
existing Codex and Claude Code pages to a shared template.
Reorganize the client integration index into client and
platform/API entry points, clarify local-vs-remote MCP
boundaries, standardize verification steps, and add focused
troubleshooting guidance for platform integrations.
* Add MCP platform integration guides
Add OpenAI Responses API, ChatGPT Developer Mode, and
Anthropic MCP Connector integration guides, and align the
existing Codex and Claude Code pages to a shared template.
Reorganize the client integration index into client and
platform/API entry points, clarify local-vs-remote MCP
boundaries, standardize verification steps, and add focused
troubleshooting guidance for platform integrations.
---
.../client-integration/_index.cn.md | 44 +++----
.../client-integration/_index.en.md | 44 +++----
.../anthropic-mcp-connector.cn.md | 129 +++++++++++++++++++++
.../anthropic-mcp-connector.en.md | 129 +++++++++++++++++++++
.../chatgpt-developer-mode.cn.md | 79 +++++++++++++
.../chatgpt-developer-mode.en.md | 79 +++++++++++++
.../client-integration/claude-code.cn.md | 72 ++++++++----
.../client-integration/claude-code.en.md | 72 ++++++++----
.../client-integration/codex.cn.md | 50 ++++++--
.../client-integration/codex.en.md | 50 ++++++--
.../client-integration/openai-responses-api.cn.md | 104 +++++++++++++++++
.../client-integration/openai-responses-api.en.md | 104 +++++++++++++++++
.../shardingsphere-mcp/troubleshooting.cn.md | 74 ++++++------
.../shardingsphere-mcp/troubleshooting.en.md | 74 ++++++------
14 files changed, 920 insertions(+), 184 deletions(-)
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 14b3385f3b6..a87e7735408 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
@@ -3,39 +3,43 @@ title = "客户端集成"
weight = 4
+++
-客户端集成用于把 ShardingSphere-MCP 接入支持 MCP 的 AI 应用、IDE 插件或 Agent 平台。
-配置完成后，用户可以在应用中通过自然语言查看元数据、执行受控 SQL 查询，或发起数据库治理任务。
+客户端集成用于把 ShardingSphere-MCP 接入支持 MCP 的 AI 客户端、产品入口或平台
API。配置完成后，用户可以在应用中通过自然语言查看元数据、执行受控 SQL 查询，或发起数据库治理任务。
-适合使用客户端集成的场景：
+可完成的任务和使用边界见[能力清单](../capabilities/)。
-- 在 AI 应用、IDE 插件或 Agent 平台中接入 ShardingSphere-MCP。
-- 通过自然语言查看元数据、执行受控 SQL 或规划 ShardingSphere 规则变更。
-- 为团队提供统一的受控数据库访问入口。
+## 客户端接入
-可完成的任务和使用边界见[能力清单](../capabilities/)。
+- [Codex](./codex/)：适合在 Codex CLI 或 IDE 扩展中接入已经启动的 HTTP MCP Server。
+- [Claude Code](./claude-code/)：适合在 Claude Code CLI 中接入已经启动的 HTTP MCP
Server，或由 Claude Code 拉起本地 STDIO MCP Server。
-## 典型客户端
+## 平台与 API 接入
-- [Codex](./codex/)：适合在 Codex CLI 或 IDE 扩展中使用 ShardingSphere-MCP。
-- [Claude Code](./claude-code/)：适合在 Claude Code 项目或用户配置中使用 ShardingSphere-MCP。
+- [OpenAI Responses API](./openai-responses-api/)：适合在后端应用中通过 OpenAI API 调用远程
MCP Server。
+- [ChatGPT Developer Mode](./chatgpt-developer-mode/)：适合在 ChatGPT Web
产品中直接接入远程 MCP Server。
+- [Anthropic MCP Connector](./anthropic-mcp-connector/)：适合在 Anthropic Messages
API 中直接接入远程 MCP Server。
-## 选择接入方式
+平台与 API 接入要求使用已受保护且远程可访问的 MCP endpoint。
+不要把 ShardingSphere-MCP 内置 HTTP Server 直接暴露给远程平台，因为它不提供认证或授权。
+远程平台接入时，应将其放在受信网关或反向代理后面，由外层组件提供 TLS 终止、身份认证、授权策略、网络访问控制和审计日志。
+安全边界见[部署说明](../deployment/)和[配置说明](../configuration/)。
+`http://127.0.0.1:18088/mcp` 这类本地地址示例只适用于本地客户端集成文档，不能直接复用于 OpenAI 或 Anthropic
平台入口。
-- 如果 ShardingSphere-MCP 已经独立启动，或者需要多个应用访问同一个服务，选择 HTTP 接入方式。
-- 如果只在本地开发环境使用，并希望 AI 应用在需要时启动 ShardingSphere-MCP，选择 STDIO 接入方式。
-- 如果使用 Codex 或 Claude Code，优先参考本章对应子页面。
-- 如果使用其他客户端，请按客户端自身文档配置 ShardingSphere-MCP 的地址或启动脚本。
+## 选择接入入口
-## 集成后的使用方式
+- 如果主要在本地开发或编码助手中使用，优先选择客户端接入。
+- 如果需要在后端服务中通过 API 调模型并调用 MCP，优先选择平台与 API 接入。
+- 如果需要多个客户端共享同一个 ShardingSphere-MCP 服务，优先准备独立启动的 HTTP MCP Server。
+- 如果只在本地开发环境使用，并希望客户端在需要时拉起 MCP 进程，可选择支持 STDIO 的客户端。
+- 如果目标入口位于 OpenAI 或 Anthropic 平台侧，优先确认已受保护的远程 MCP 地址是否可从平台访问，再继续后续接入步骤。
-AI 应用完成 MCP Server 配置后，用户在对话中直接描述任务。
+## 集成后的使用方式
-示例：
+完成配置后，用户可以在对话中直接描述任务，例如：
- 查看 `<logic-database>` 中有哪些表。
- 查询 `<table-name>` 的字段和索引。
- 执行一条只读查询，并限制返回 100 行。
+- 调用 `database_gateway_validate_proxy_connectivity` 对已经配置的 runtime database
进行接入前校验。
- 规划一个数据加密或数据脱敏规则，先预览不要执行。
-涉及 SQL 执行、规则变更或规则变更计划执行时，应先审查预览内容，再确认执行。
-自研集成或协议调试场景见[自研集成附录](../developer-appendix/)。
+涉及 SQL
执行、规则变更或规则变更计划执行时，应先审查预览内容，再确认执行。自研集成或协议调试场景见[自研集成附录](../developer-appendix/)。
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 e5ce5e68209..03f503bf0f8 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
@@ -3,39 +3,43 @@ title = "Client Integration"
weight = 4
+++
-Client integration connects ShardingSphere-MCP to MCP-capable AI applications,
IDE extensions, or agent platforms.
-After configuration, users can inspect metadata, run controlled SQL queries,
or start database governance tasks through natural language in the application.
+Client integration connects ShardingSphere-MCP to MCP-capable AI clients,
product entry points, and platform APIs. After configuration, users can inspect
metadata, run controlled SQL queries, or start database governance tasks
through natural language in the application.
-Use client integration when:
+See the [Capability Catalog](../capabilities/) for supported tasks and usage
boundaries.
-- 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.
+## Client integrations
-See [Capability Catalog](../capabilities/) for supported tasks and usage
boundaries.
+- [Codex](./codex/) connects an already running HTTP MCP Server to Codex CLI
or the Codex IDE extension.
+- [Claude Code](./claude-code/) connects an already running HTTP MCP Server to
Claude Code CLI, or lets Claude Code start a local STDIO MCP Server.
-## Typical Clients
+## Platform and API integrations
-- [Codex](./codex/): use ShardingSphere-MCP in Codex CLI or IDE extension.
-- [Claude Code](./claude-code/): use ShardingSphere-MCP in Claude Code project
or user configuration.
+- [OpenAI Responses API](./openai-responses-api/) connects a remote MCP Server
through the OpenAI API in backend applications.
+- [ChatGPT Developer Mode](./chatgpt-developer-mode/) connects a remote MCP
Server directly in the ChatGPT web product.
+- [Anthropic MCP Connector](./anthropic-mcp-connector/) connects a remote MCP
Server directly in the Anthropic Messages API.
-## Choose an Integration Method
+Platform and API integrations require a secured, remotely reachable MCP
endpoint.
+Do not expose the built-in ShardingSphere-MCP HTTP Server directly to remote
platforms because it does not provide authentication or authorization.
+For remote platform access, place it behind a trusted gateway or reverse proxy
that provides TLS termination, authentication, authorization policy, network
access control, and audit logs.
+See [Deployment](../deployment/) and [Configuration](../configuration/) for
the security boundary.
+Local examples such as `http://127.0.0.1:18088/mcp` are only suitable for
local client integration pages and cannot be reused directly for OpenAI or
Anthropic platform entry points.
-- If ShardingSphere-MCP is already started independently, or multiple
applications need to access the same service, choose HTTP integration.
-- If it is used only in a local development environment and the AI application
should start ShardingSphere-MCP when needed, choose STDIO integration.
-- If you use Codex or Claude Code, start with the corresponding page in this
section.
-- If you use another client, follow that client's documentation and configure
the ShardingSphere-MCP address or startup script.
+## Choose an entry point
-## Using the Integration
+- Use a client integration when ShardingSphere-MCP is primarily used in local
development or coding assistants.
+- Use a platform or API integration when a backend service needs to call
models through an API and let those models call MCP tools.
+- When multiple clients should share the same ShardingSphere-MCP service,
prefer an independently started HTTP MCP Server.
+- When the MCP process should start only on demand in local development,
choose a client that supports STDIO.
+- When the target entry point runs inside OpenAI or Anthropic infrastructure,
confirm that the secured remote MCP address is reachable from that platform
before continuing.
-After the AI application is configured with the MCP Server, users describe
tasks directly in the conversation.
+## Typical usage after integration
-Examples:
+After configuration, users describe tasks directly in the conversation.
Examples:
- Show the tables in `<logic-database>`.
- Inspect columns and indexes for `<table-name>`.
- Run a read-only query and limit the result to 100 rows.
+- Call `database_gateway_validate_proxy_connectivity` for a configured runtime
database.
- Plan a data encryption or data masking rule and preview it without execution.
-When SQL execution, rule changes, or rule change plan execution is involved,
review the preview content before confirming execution.
-For custom integration or protocol debugging, see the [Custom Integration
Appendix](../developer-appendix/).
+When SQL execution, rule changes, or rule change plan execution is involved,
review the preview content before confirming execution. For custom integration
or protocol debugging, see the [Custom Integration
Appendix](../developer-appendix/).
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/anthropic-mcp-connector.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/anthropic-mcp-connector.cn.md
new file mode 100644
index 00000000000..51fcc71648e
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/anthropic-mcp-connector.cn.md
@@ -0,0 +1,129 @@
++++
+title = "Anthropic MCP Connector"
+weight = 5
++++
+
+本页说明如何在 Anthropic Messages API 中通过 MCP Connector 接入已经启动的 ShardingSphere-MCP
HTTP Server。ShardingSphere-MCP 是 Apache ShardingSphere 提供的 MCP
Server，用于把数据库元数据访问、受控 SQL 查询和数据库治理能力暴露给支持 MCP 的 AI 客户端和平台。
+
+## 适用场景
+
+- 适合在 Anthropic Messages API 中直接挂接远程 ShardingSphere-MCP，而不单独实现 MCP client。
+- 适合在 Claude API 请求中按需暴露 ShardingSphere-MCP 的元数据查询、受控查询、规则规划和接入前预检能力。
+- 接入完成后，可以在 Claude 会话中查看逻辑库中的表、查看表结构，或调用
`database_gateway_validate_proxy_connectivity` 对已经配置的 runtime database 进行接入前校验。
+
+## 前置条件
+
+- 已按[快速开始](../../quick-start/)启动 HTTP MCP Server。
+- 只暴露可被 Anthropic Messages API 访问且已受保护的远程 HTTPS endpoint。ShardingSphere-MCP 内置
HTTP Server 不提供认证或授权。
+- 远程平台接入时，应将 ShardingSphere-MCP 放在受信网关或反向代理后面，由外层组件提供 TLS 终止、身份认证、
+ 授权策略、网络访问控制和审计日志。
+ 安全边界见[部署说明](../../deployment/)和[配置说明](../../configuration/)。
+- 该受保护的远程 endpoint 需要支持 `Streamable HTTP` 或 `SSE`。
+- 已准备 Anthropic API Key。
+- 当前 MCP Connector 版本要求携带 `anthropic-beta: mcp-client-2025-11-20` 请求头。
+- 如果受保护的远程 endpoint 或网关使用 OAuth 或 Bearer 认证，需要提前准备可传入 `authorization_token`
的访问令牌。
+
+## 接入步骤
+
+### 配置接入
+
+在 Messages API 请求中，先用 `mcp_servers` 声明 ShardingSphere-MCP，再在 `tools`
数组里添加与之对应的 `mcp_toolset`。最小示例如下：
+
+```bash
+curl https://api.anthropic.com/v1/messages \
+ -H "content-type: application/json" \
+ -H "x-api-key: $ANTHROPIC_API_KEY" \
+ -H "anthropic-version: 2023-06-01" \
+ -H "anthropic-beta: mcp-client-2025-11-20" \
+ -d '{
+ "model": "claude-sonnet-4-5",
+ "max_tokens": 1024,
+ "messages": [
+ {
+ "role": "user",
+ "content": "Use ShardingSphere-MCP to inspect the tables in the logic
database."
+ }
+ ],
+ "mcp_servers": [
+ {
+ "type": "url",
+ "url": "https://example.com/mcp";,
+ "name": "shardingsphere"
+ }
+ ],
+ "tools": [
+ {
+ "type": "mcp_toolset",
+ "mcp_server_name": "shardingsphere"
+ }
+ ]
+ }'
+```
+
+如果受保护的远程 endpoint 或网关使用 OAuth 或 Bearer 认证，可以在 `mcp_servers` 条目中增加：
+
+```json
+"authorization_token": "YOUR_TOKEN"
+```
+
+如果只想暴露一部分工具，可以在 `mcp_toolset` 中使用 `default_config` 和 `configs` 做 allowlist 或
denylist。例如，把默认值设为禁用，再显式启用少量工具：
+
+```json
+{
+ "type": "mcp_toolset",
+ "mcp_server_name": "shardingsphere",
+ "default_config": {
+ "enabled": false
+ },
+ "configs": {
+ "database_gateway_search_metadata": {
+ "enabled": true
+ },
+ "database_gateway_validate_proxy_connectivity": {
+ "enabled": true
+ }
+ }
+}
+```
+
+### 验证接入成功
+
+识别成功：
+
+- 先用一条最小请求确认 `mcp_servers` 与 `mcp_toolset` 已正确配对，没有触发服务名不匹配或 toolset 悬空错误。
+
+调用成功：
+
+- 在 Claude 会话中执行一条最小验证任务，例如：
+ - 查看 `<logic-database>` 中有哪些表。
+ - 查看 `orders` 表的列和索引。
+ - 对已经配置的 runtime database 调用 `database_gateway_validate_proxy_connectivity`。
+- 如果 Claude 能返回来自 ShardingSphere-MCP 的工具结果，说明接入已经生效。
+
+如果接入失败，优先检查：
+
+- 是否携带了 `anthropic-beta: mcp-client-2025-11-20` 请求头。
+- `mcp_servers` 中的 `name` 和 `mcp_toolset` 中的 `mcp_server_name` 是否严格一致。
+- 远程地址是否为 Anthropic 平台可访问且已受保护的 HTTPS MCP endpoint，而不是本地 `127.0.0.1`
地址或直接暴露的未认证内置 HTTP Server。
+
+## 注意事项
+
+- Anthropic MCP Connector 当前只支持远程 HTTP MCP Server，不支持本地 `STDIO` 进程。
+- 当前平台侧只支持 tool calls，不提供完整 MCP 资源面接入。
+- 默认情况下 `mcp_toolset` 会启用远程 MCP Server 暴露的全部工具。对于只读助手或受控试用环境，建议显式禁用不需要的写入类工具。
+- 该功能当前要求 `anthropic-beta: mcp-client-2025-11-20` 请求头；如果官方更新 beta
版本，需要同步调整文档与调用配置。
+- 本页只说明 Anthropic 平台 API 接入方式。若希望在 Claude Code CLI 中接入，请参考 [Claude
Code](../claude-code/)。
+- 具体可用任务和使用边界见[能力清单](../../capabilities/)。
+
+## 参考资料
+
+### 相关文档
+
+- [快速开始](../../quick-start/)
+- [能力清单](../../capabilities/)
+- [配置说明](../../configuration/)
+- [Claude Code](../claude-code/)
+
+### 官方参考
+
+- [MCP
connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector)
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/anthropic-mcp-connector.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/anthropic-mcp-connector.en.md
new file mode 100644
index 00000000000..2bc8613f4f3
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/anthropic-mcp-connector.en.md
@@ -0,0 +1,129 @@
++++
+title = "Anthropic MCP Connector"
+weight = 5
++++
+
+This page explains how to connect an already running ShardingSphere-MCP HTTP
Server through the Anthropic MCP Connector in the Messages API.
ShardingSphere-MCP is the Apache ShardingSphere MCP Server that exposes
database metadata access, controlled SQL queries, and database governance
capabilities to MCP-capable AI clients and platforms.
+
+## Applicable Scenarios
+
+- Use this page when you want to attach a remote ShardingSphere-MCP server
directly in the Anthropic Messages API without implementing a separate MCP
client.
+- Use this integration when Claude API requests should expose
ShardingSphere-MCP tools for metadata queries, controlled queries, rule
planning, and preflight validation.
+- After integration, Claude can inspect logic databases, inspect table
structures, or call `database_gateway_validate_proxy_connectivity` for
preflight validation against configured runtime databases.
+
+## Prerequisites
+
+- Start the HTTP MCP Server by following [Quick Start](../../quick-start/).
+- Expose only a secured remote HTTPS endpoint that the Anthropic Messages API
can reach. The built-in ShardingSphere-MCP HTTP Server does not provide
authentication or authorization.
+- For remote platform access, place ShardingSphere-MCP behind a trusted
gateway or reverse proxy that provides TLS termination, authentication,
+ authorization policy, network access control, and audit logs.
+ See [Deployment](../../deployment/) and
[Configuration](../../configuration/) for the security boundary.
+- The secured remote endpoint supports `Streamable HTTP` or `SSE`.
+- Prepare an Anthropic API key.
+- The current MCP Connector version requires the request header
`anthropic-beta: mcp-client-2025-11-20`.
+- If the secured remote endpoint or gateway requires OAuth or Bearer
authentication, prepare an access token that can be passed as
`authorization_token`.
+
+## Integration Steps
+
+### Configure the integration
+
+In a Messages API request, declare ShardingSphere-MCP in `mcp_servers` first,
then add the matching `mcp_toolset` in the `tools` array. A minimal example is:
+
+```bash
+curl https://api.anthropic.com/v1/messages \
+ -H "content-type: application/json" \
+ -H "x-api-key: $ANTHROPIC_API_KEY" \
+ -H "anthropic-version: 2023-06-01" \
+ -H "anthropic-beta: mcp-client-2025-11-20" \
+ -d '{
+ "model": "claude-sonnet-4-5",
+ "max_tokens": 1024,
+ "messages": [
+ {
+ "role": "user",
+ "content": "Use ShardingSphere-MCP to inspect the tables in the logic
database."
+ }
+ ],
+ "mcp_servers": [
+ {
+ "type": "url",
+ "url": "https://example.com/mcp";,
+ "name": "shardingsphere"
+ }
+ ],
+ "tools": [
+ {
+ "type": "mcp_toolset",
+ "mcp_server_name": "shardingsphere"
+ }
+ ]
+ }'
+```
+
+If the secured remote endpoint or gateway requires OAuth or Bearer
authentication, add this field to the `mcp_servers` entry:
+
+```json
+"authorization_token": "YOUR_TOKEN"
+```
+
+To expose only a subset of tools, use `default_config` and `configs` in the
`mcp_toolset` as an allowlist or denylist. For example, disable everything by
default and enable only a small subset:
+
+```json
+{
+ "type": "mcp_toolset",
+ "mcp_server_name": "shardingsphere",
+ "default_config": {
+ "enabled": false
+ },
+ "configs": {
+ "database_gateway_search_metadata": {
+ "enabled": true
+ },
+ "database_gateway_validate_proxy_connectivity": {
+ "enabled": true
+ }
+ }
+}
+```
+
+### Verify the integration
+
+Recognition succeeds when:
+
+- Start with a minimal request to confirm that `mcp_servers` and `mcp_toolset`
are correctly paired and do not trigger validation errors for mismatched server
names or dangling toolsets.
+
+Invocation succeeds when:
+
+- In a Claude conversation, run a minimal validation task such as:
+ - Show the tables in `<logic-database>`.
+ - Show columns and indexes for the `orders` table.
+ - Call `database_gateway_validate_proxy_connectivity` for a configured
runtime database.
+- If Claude returns tool results from ShardingSphere-MCP, the integration is
working.
+
+If the integration fails, check these items first:
+
+- Confirm that the request includes the `anthropic-beta:
mcp-client-2025-11-20` header.
+- Confirm that the `name` in `mcp_servers` exactly matches `mcp_server_name`
in the `mcp_toolset`.
+- Confirm that the remote address is a secured HTTPS MCP endpoint reachable
from Anthropic, not a local `127.0.0.1` address or a directly exposed
unauthenticated built-in HTTP Server.
+
+## Notes
+
+- The Anthropic MCP Connector currently supports remote HTTP MCP Servers only.
It does not connect to local `STDIO` processes.
+- The platform integration currently supports tool calls only. It does not
expose the full MCP resource surface.
+- By default, `mcp_toolset` enables all tools exposed by the remote MCP
Server. For read-only assistants or controlled trial environments, explicitly
disable write-oriented tools that are not needed.
+- This feature currently requires the `anthropic-beta: mcp-client-2025-11-20`
header. If Anthropic updates the beta version, update the documentation and the
request configuration together.
+- This page covers the Anthropic platform API path only. For Claude Code CLI
integration, use [Claude Code](../claude-code/).
+- See the [Capability Catalog](../../capabilities/) for the supported task
surface and usage boundaries.
+
+## References
+
+### Related documents
+
+- [Quick Start](../../quick-start/)
+- [Capability Catalog](../../capabilities/)
+- [Configuration](../../configuration/)
+- [Claude Code](../claude-code/)
+
+### Official references
+
+- [MCP
connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector)
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/chatgpt-developer-mode.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/chatgpt-developer-mode.cn.md
new file mode 100644
index 00000000000..11bab3b9f48
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/chatgpt-developer-mode.cn.md
@@ -0,0 +1,79 @@
++++
+title = "ChatGPT Developer Mode"
+weight = 4
++++
+
+本页说明如何在 ChatGPT Developer Mode 中接入已经启动的 ShardingSphere-MCP HTTP
Server。ShardingSphere-MCP 是 Apache ShardingSphere 提供的 MCP Server，用于把数据库元数据访问、受控
SQL 查询和数据库治理能力暴露给支持 MCP 的 AI 客户端和平台。
+
+## 适用场景
+
+- 适合在 ChatGPT Web 产品中直接接入远程 ShardingSphere-MCP，而不经过自定义后端代码。
+- 适合在 ChatGPT 会话里选择一个远程 MCP App，并直接调用 ShardingSphere-MCP
提供的元数据查询、受控查询、规则规划或接入前预检能力。
+- 接入完成后，可以在 ChatGPT 对话中查看逻辑库中的表、查看表结构，或调用
`database_gateway_validate_proxy_connectivity` 对已经配置的 runtime database 进行接入前校验。
+
+## 前置条件
+
+- 已按[快速开始](../../quick-start/)启动 HTTP MCP Server。
+- 只暴露可被 ChatGPT 访问且已受保护的远程 endpoint。ShardingSphere-MCP 内置 HTTP Server 不提供认证或授权。
+- 远程平台接入时，应将 ShardingSphere-MCP 放在受信网关或反向代理后面，由外层组件提供 TLS 终止、身份认证、
+ 授权策略、网络访问控制和审计日志。
+ 安全边界见[部署说明](../../deployment/)和[配置说明](../../configuration/)。
+- 该受保护的远程 endpoint 需要支持 `SSE` 或 `streaming HTTP`。
+- 已准备可用的 ChatGPT Web 账号。当前 Developer Mode 在 Web 端 Beta 提供给
Pro、Plus、Business、Enterprise 和 Education 账号。
+- 提前确定受保护的远程 endpoint 使用 `OAuth`、`No Authentication` 或 `Mixed Authentication`
中的哪一种模式。
+ `No Authentication` 仅适用于受控私有测试，或外层网络边界已经限制访问的 endpoint。
+
+## 接入步骤
+
+### 配置接入
+
+1. 在 ChatGPT Web 中进入 `Settings -> Apps -> Advanced settings -> Developer
mode`，启用 Developer Mode。
+2. 打开 App 设置页，使用 `Create app` 为 ShardingSphere-MCP 创建一个新的 app。
+3. 在 app 配置中填写 ShardingSphere-MCP 的受保护远程地址，并选择与 endpoint 匹配的认证方式：
+ - `OAuth`
+ - `No Authentication`，仅适用于受控私有测试或已经由外层边界限制访问的 endpoint
+ - `Mixed Authentication`
+4. 保存 app 配置，并在 app 详情页刷新工具列表，使 ChatGPT 从 ShardingSphere-MCP 拉取最新工具和描述。
+
+### 验证接入成功
+
+识别成功：
+
+- 在 app 设置页中确认新建的 ShardingSphere-MCP app 已经出现，并能看到导入的工具列表。
+- 在 ChatGPT 会话中切换到 Developer Mode，并选中该 app。
+
+调用成功：
+
+- 先执行一条最小验证任务，例如：
+ - 查看 `<logic-database>` 中有哪些表。
+ - 查看 `orders` 表的列和索引。
+ - 对已经配置的 runtime database 调用 `database_gateway_validate_proxy_connectivity`。
+- 如果 ChatGPT 能识别到对应 app，并能按预期调用导入工具，说明接入已经生效。
+
+如果接入失败，优先检查：
+
+- 远程 MCP 地址是否为 ChatGPT 可访问且已受保护的远程地址，而不是本地 `127.0.0.1` 地址或直接暴露的未认证内置 HTTP
Server。
+- app 保存后是否已刷新工具列表，并成功拉取到 ShardingSphere-MCP 暴露的工具。
+- 认证模式是否与 MCP Server 的实际配置一致。
+
+## 注意事项
+
+- ChatGPT Developer Mode 支持读写工具。涉及 SQL 执行或规则变更时，应仔细审查模型发起的写操作和审批提示。
+- 该入口只适用于远程 MCP Server，不适用于本地 `STDIO` 进程。
+- 如果一个会话中同时启用了多个 app，建议在提示中显式指定应优先使用 ShardingSphere-MCP。
+- 本页只说明 ChatGPT 产品界面接入，不覆盖 OpenAI API 代码集成。后者请参考 [OpenAI Responses
API](../openai-responses-api/)。
+- 具体可用任务和使用边界见[能力清单](../../capabilities/)。
+
+## 参考资料
+
+### 相关文档
+
+- [快速开始](../../quick-start/)
+- [能力清单](../../capabilities/)
+- [配置说明](../../configuration/)
+- [Codex](../codex/)
+- [OpenAI Responses API](../openai-responses-api/)
+
+### 官方参考
+
+- [ChatGPT Developer
mode](https://platform.openai.com/docs/guides/developer-mode)
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/chatgpt-developer-mode.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/chatgpt-developer-mode.en.md
new file mode 100644
index 00000000000..3d8457db588
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/chatgpt-developer-mode.en.md
@@ -0,0 +1,79 @@
++++
+title = "ChatGPT Developer Mode"
+weight = 4
++++
+
+This page explains how to connect an already running ShardingSphere-MCP HTTP
Server in ChatGPT Developer Mode. ShardingSphere-MCP is the Apache
ShardingSphere MCP Server that exposes database metadata access, controlled SQL
queries, and database governance capabilities to MCP-capable AI clients and
platforms.
+
+## Applicable Scenarios
+
+- Use this page when you want to connect a remote ShardingSphere-MCP server
directly in the ChatGPT web product without writing backend integration code.
+- Use this integration when ChatGPT conversations should select a remote MCP
app and directly call ShardingSphere-MCP tools for metadata queries, controlled
queries, rule planning, or preflight validation.
+- After integration, ChatGPT can inspect logic databases, inspect table
structures, or call `database_gateway_validate_proxy_connectivity` for
preflight validation against configured runtime databases.
+
+## Prerequisites
+
+- Start the HTTP MCP Server by following [Quick Start](../../quick-start/).
+- Expose only a secured remote endpoint that ChatGPT can reach. The built-in
ShardingSphere-MCP HTTP Server does not provide authentication or authorization.
+- For remote platform access, place ShardingSphere-MCP behind a trusted
gateway or reverse proxy that provides TLS termination, authentication,
+ authorization policy, network access control, and audit logs.
+ See [Deployment](../../deployment/) and
[Configuration](../../configuration/) for the security boundary.
+- The secured remote endpoint supports `SSE` or `streaming HTTP`.
+- Use a ChatGPT web account that is eligible for Developer Mode. The current
beta is available on the web to Pro, Plus, Business, Enterprise, and Education
accounts.
+- Decide whether the secured remote endpoint uses `OAuth`, `No
Authentication`, or `Mixed Authentication`.
+ Use `No Authentication` only for controlled private testing or when an outer
network boundary already restricts access.
+
+## Integration Steps
+
+### Configure the integration
+
+1. In ChatGPT Web, go to `Settings -> Apps -> Advanced settings -> Developer
mode` and enable Developer Mode.
+2. Open the app settings page and use `Create app` to create a new app for
ShardingSphere-MCP.
+3. In the app configuration, enter the secured remote ShardingSphere-MCP
address and select the authentication mode that matches the endpoint:
+ - `OAuth`
+ - `No Authentication` for controlled private testing or an already
restricted endpoint only
+ - `Mixed Authentication`
+4. Save the app and refresh the tool list on the app details page so ChatGPT
can pull the latest tools and descriptions from ShardingSphere-MCP.
+
+### Verify the integration
+
+Recognition succeeds when:
+
+- In the app settings page, confirm that the ShardingSphere-MCP app exists and
that imported tools are visible.
+- In a ChatGPT conversation, switch to Developer Mode and select the app.
+
+Invocation succeeds when:
+
+- Start with a minimal validation task such as:
+ - Show the tables in `<logic-database>`.
+ - Show columns and indexes for the `orders` table.
+ - Call `database_gateway_validate_proxy_connectivity` for a configured
runtime database.
+- If ChatGPT recognizes the app and can invoke its imported tools, the
integration is working.
+
+If the integration fails, check these items first:
+
+- Confirm that the remote MCP address is reachable from ChatGPT and is not a
local `127.0.0.1` address or a directly exposed unauthenticated built-in HTTP
Server.
+- Confirm that the tool list was refreshed after saving the app and that
ChatGPT successfully imported the ShardingSphere-MCP tools.
+- Confirm that the selected authentication mode matches the actual MCP Server
configuration.
+
+## Notes
+
+- ChatGPT Developer Mode supports both read and write tools. Review write
actions and approval prompts carefully before allowing SQL execution or rule
changes.
+- This entry point works only with remote MCP Servers. It does not connect to
local `STDIO` processes.
+- When multiple apps are enabled in the same conversation, explicitly tell
ChatGPT to prefer ShardingSphere-MCP.
+- This page covers the ChatGPT product UI path only. For OpenAI API code
integration, use [OpenAI Responses API](../openai-responses-api/).
+- See the [Capability Catalog](../../capabilities/) for the supported task
surface and usage boundaries.
+
+## References
+
+### Related documents
+
+- [Quick Start](../../quick-start/)
+- [Capability Catalog](../../capabilities/)
+- [Configuration](../../configuration/)
+- [Codex](../codex/)
+- [OpenAI Responses API](../openai-responses-api/)
+
+### Official references
+
+- [ChatGPT Developer
mode](https://platform.openai.com/docs/guides/developer-mode)
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/claude-code.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/claude-code.cn.md
index 3898d9c1874..c79aa9cd3f6 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/claude-code.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/claude-code.cn.md
@@ -3,7 +3,13 @@ title = "Claude Code"
weight = 2
+++
-本页说明如何在 Claude Code 中接入已经启动的 ShardingSphere-MCP HTTP Server，或由 Claude Code
拉起本地 STDIO MCP Server。
+本页说明如何在 Claude Code 中接入已经启动的 ShardingSphere-MCP HTTP Server，或由 Claude Code
拉起本地 STDIO MCP Server。ShardingSphere-MCP 是 Apache ShardingSphere 提供的 MCP
Server，用于把数据库元数据访问、受控 SQL 查询和数据库治理能力暴露给支持 MCP 的 AI 客户端和平台。
+
+## 适用场景
+
+- 适合在 Claude Code CLI 中接入已经启动的 ShardingSphere-MCP HTTP Server。
+- 适合在本地开发环境中由 Claude Code 直接拉起 ShardingSphere-MCP STDIO 进程。
+- 接入完成后，可以在 Claude Code 中查看逻辑库中的表、查看表结构、执行受控只读查询，或调用
`database_gateway_validate_proxy_connectivity` 进行接入前校验。
## 前置条件
@@ -11,24 +17,19 @@ weight = 2
- Claude Code CLI 可用。
- 使用 HTTP 方式时，Claude Code 所在环境可以访问 `http://127.0.0.1:18088/mcp`，或访问你实际配置的 MCP
Server 地址。
-## 添加 HTTP MCP Server
-
-在使用 Claude Code 的项目目录中执行：
+## 接入步骤
-```bash
-claude mcp add --transport http shardingsphere http://127.0.0.1:18088/mcp
-```
+### 接入方式选择
-查看是否添加成功：
+- 如果 ShardingSphere-MCP 已经独立启动，或者需要多个应用共享同一个服务，选择 HTTP 接入。
+- 如果只在本地开发环境中使用，并希望 Claude Code 在需要时启动 ShardingSphere-MCP，选择 STDIO 接入。
-```bash
-claude mcp list
-```
+### 配置接入
-在 Claude Code 中运行：
+使用 HTTP MCP Server：
-```text
-/mcp
+```bash
+claude mcp add --transport http shardingsphere http://127.0.0.1:18088/mcp
```
如果希望当前用户的所有 Claude Code 项目都可使用该 MCP Server，可以使用用户级配置：
@@ -50,8 +51,6 @@ claude mcp add --transport http --scope user shardingsphere
http://127.0.0.1:180
}
```
-## 使用 STDIO MCP Server
-
如果希望 Claude Code 在本地拉起 ShardingSphere-MCP 进程，可以使用 STDIO：
```bash
@@ -62,17 +61,42 @@ claude mcp add --transport stdio shardingsphere -- \
将 `/path/to/apache-shardingsphere-mcp` 替换为实际发行包目录。
-## 使用方式
+### 验证接入成功
+
+识别成功：
+
+- 运行 `claude mcp list`，确认 `shardingsphere` 已出现在 MCP Server 列表中。
+- 在 Claude Code 中运行：
+
+```text
+/mcp
+```
+
+调用成功：
+
+- 在 Claude Code 对话中执行一条最小验证任务，例如：
+ - 查看 `<logic-database>` 中有哪些表。
+ - 查看 `orders` 表的列和索引。
+ - 对已经配置的 runtime database 执行 `database_gateway_validate_proxy_connectivity`。
+- 如果工具已被列出并能返回查询结果，说明接入已经生效。
+
+## 注意事项
+
+- 使用 STDIO 时，Claude Code 需要能够访问本地 ShardingSphere-MCP 发行包和对应配置文件。
+- 同一个 `shardingsphere` server name 应只对应一种接入方式；如果需要同时保留 HTTP 与 STDIO，建议使用不同的
server name。
+- 具体可用任务和使用边界见[能力清单](../../capabilities/)。
+- 涉及 SQL 执行或规则变更时，应先审查预览内容，再确认执行。
+- 如果希望通过 Anthropic API 平台侧接入 ShardingSphere-MCP，请参考 [Anthropic MCP
Connector](../anthropic-mcp-connector/)。
-在 Claude Code 中直接描述数据库任务，例如：
+## 参考资料
-- 查看 `<logic-database>` 中有哪些表。
-- 查看 `orders` 表的列和索引。
-- 查询 `orders` 表前 10 行。
-- 为 `orders.status` 规划可逆加密，先预览不要执行。
+### 相关文档
-涉及 SQL 执行或规则变更时，应先审查预览内容，再确认执行。
+- [快速开始](../../quick-start/)
+- [能力清单](../../capabilities/)
+- [配置说明](../../configuration/)
+- [Anthropic MCP Connector](../anthropic-mcp-connector/)
-## 参考
+### 官方参考
- [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp)
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/claude-code.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/claude-code.en.md
index 70c2f0d6756..e3a33faf76e 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/claude-code.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/claude-code.en.md
@@ -3,7 +3,13 @@ title = "Claude Code"
weight = 2
+++
-This page explains how to connect Claude Code to an already running
ShardingSphere-MCP HTTP Server, or let Claude Code start a local STDIO MCP
Server.
+This page explains how to connect Claude Code to an already running
ShardingSphere-MCP HTTP Server, or let Claude Code start a local STDIO MCP
Server. ShardingSphere-MCP is the Apache ShardingSphere MCP Server that exposes
database metadata access, controlled SQL queries, and database governance
capabilities to MCP-capable AI clients and platforms.
+
+## Applicable Scenarios
+
+- Use this page when you want to connect an already running ShardingSphere-MCP
HTTP Server to Claude Code CLI.
+- Use this page when you want Claude Code to start ShardingSphere-MCP locally
through STDIO in a local development environment.
+- After integration, Claude Code can inspect logic databases, inspect table
structures, run controlled read-only queries, or call
`database_gateway_validate_proxy_connectivity` for preflight validation.
## Prerequisites
@@ -11,24 +17,19 @@ This page explains how to connect Claude Code to an already
running ShardingSphe
- Claude Code CLI is available.
- For HTTP transport, the Claude Code environment can reach
`http://127.0.0.1:18088/mcp`, or the actual MCP Server address you configured.
-## Add an HTTP MCP Server
-
-Run the following command from the project where you use Claude Code:
+## Integration Steps
-```bash
-claude mcp add --transport http shardingsphere http://127.0.0.1:18088/mcp
-```
+### Choose an integration method
-Verify that it has been added:
+- Choose HTTP when ShardingSphere-MCP is already started independently, or
when multiple applications need to share the same service.
+- Choose STDIO when ShardingSphere-MCP is only used in a local development
environment and Claude Code should start it on demand.
-```bash
-claude mcp list
-```
+### Configure the integration
-Run the following command in Claude Code:
+Use an HTTP MCP Server:
-```text
-/mcp
+```bash
+claude mcp add --transport http shardingsphere http://127.0.0.1:18088/mcp
```
To make the MCP Server available across all Claude Code projects for the
current user, use user scope:
@@ -50,8 +51,6 @@ You can also create `.mcp.json` in the project root:
}
```
-## Use the STDIO MCP Server
-
If you want Claude Code to start ShardingSphere-MCP as a local process, use
STDIO:
```bash
@@ -62,17 +61,42 @@ claude mcp add --transport stdio shardingsphere -- \
Replace `/path/to/apache-shardingsphere-mcp` with the actual distribution
directory.
-## Usage
+### Verify the integration
+
+Recognition succeeds when:
+
+- Run `claude mcp list` and confirm that `shardingsphere` appears in the MCP
Server list.
+- Run the following command in Claude Code:
+
+```text
+/mcp
+```
+
+Invocation succeeds when:
+
+- In a Claude Code conversation, run a minimal validation task such as:
+ - Show the tables in `<logic-database>`.
+ - Show columns and indexes for the `orders` table.
+ - Run `database_gateway_validate_proxy_connectivity` against a configured
runtime database.
+- If the tools are listed and the validation query succeeds, the integration
is working.
+
+## Notes
+
+- When using STDIO, Claude Code must be able to access the local
ShardingSphere-MCP distribution and the matching configuration file.
+- A single `shardingsphere` server name should map to only one integration
method. If you need both HTTP and STDIO, use different server names.
+- See the [Capability Catalog](../../capabilities/) for the supported task
surface and usage boundaries.
+- When SQL execution or rule changes are involved, review the preview content
before confirming execution.
+- If you want to integrate ShardingSphere-MCP through the Anthropic platform
API, use [Anthropic MCP Connector](../anthropic-mcp-connector/) instead.
-Describe database tasks directly in Claude Code, for example:
+## References
-- Show the tables in `<logic-database>`.
-- Show columns and indexes for the `orders` table.
-- Query the first 10 rows from the `orders` table.
-- Plan reversible encryption for `orders.status` and preview it without
execution.
+### Related documents
-When SQL execution or rule changes are involved, review the preview content
before confirming execution.
+- [Quick Start](../../quick-start/)
+- [Capability Catalog](../../capabilities/)
+- [Configuration](../../configuration/)
+- [Anthropic MCP Connector](../anthropic-mcp-connector/)
-## Reference
+### Official references
- [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp)
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/codex.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/codex.cn.md
index 854ca95e91a..b0e155f1d81 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/codex.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/codex.cn.md
@@ -3,7 +3,13 @@ title = "Codex"
weight = 1
+++
-本页说明如何在 Codex 中接入已经启动的 ShardingSphere-MCP HTTP Server。
+本页说明如何在 Codex 中接入已经启动的 ShardingSphere-MCP HTTP Server。ShardingSphere-MCP 是
Apache ShardingSphere 提供的 MCP Server，用于把数据库元数据访问、受控 SQL 查询和数据库治理能力暴露给支持 MCP 的
AI 客户端和平台。
+
+## 适用场景
+
+- 适合在 Codex CLI 或 Codex IDE 扩展中使用已经启动的 ShardingSphere-MCP HTTP Server。
+- 适合把数据库元数据查询、只读 SQL 查询、规则规划和接入前预检能力带入 Codex 会话。
+- 接入完成后，可以在 Codex 中查看逻辑库中的表、查看表结构、执行受控只读查询，或调用
`database_gateway_validate_proxy_connectivity` 进行接入前校验。
## 前置条件
@@ -11,7 +17,9 @@ weight = 1
- Codex CLI 或 Codex IDE 扩展可用。
- Codex 所在环境可以访问 `http://127.0.0.1:18088/mcp`，或访问你实际配置的 MCP Server 地址。
-## 添加 MCP Server
+## 接入步骤
+
+### 配置接入
使用 Codex CLI 添加 ShardingSphere-MCP：
@@ -34,17 +42,37 @@ url = "http://127.0.0.1:18088/mcp";
如果 MCP Server 地址不是默认值，请把 URL 替换为实际地址。
-## 使用方式
+### 验证接入成功
+
+识别成功：
+
+- 运行 `codex mcp list`，确认 `shardingsphere` 已出现在 MCP Server 列表中。
+
+调用成功：
+
+- 在 Codex 会话中执行一条最小验证任务，例如：
+ - 查看 `<logic-database>` 中有哪些表。
+ - 查看 `orders` 表的列和索引。
+ - 对已经配置的 runtime database 执行 `database_gateway_validate_proxy_connectivity`。
+- 如果工具列表和查询结果可返回，说明接入已经生效。
+
+## 注意事项
+
+- 本页只说明通过已经启动的 HTTP MCP Server 接入 Codex，不覆盖本地 `STDIO` 进程拉起模式。
+- 具体可用任务和使用边界见[能力清单](../../capabilities/)。
+- 涉及 SQL 执行或规则变更时，应先审查预览内容，再确认执行。
+- 如果希望在 OpenAI API 或 ChatGPT 产品中接入 ShardingSphere-MCP，请分别参考平台与 API
接入文档，而不要直接复用本页步骤。
-在 Codex 会话中直接描述数据库任务，例如：
+## 参考资料
-- 查看 `<logic-database>` 中有哪些表。
-- 查看 `orders` 表的列和索引。
-- 查询 `orders` 表前 10 行。
-- 为 `orders.phone` 规划脱敏规则，先预览不要执行。
+### 相关文档
-涉及 SQL 执行或规则变更时，应先审查预览内容，再确认执行。
+- [快速开始](../../quick-start/)
+- [能力清单](../../capabilities/)
+- [配置说明](../../configuration/)
+- [OpenAI Responses API](../openai-responses-api/)
+- [ChatGPT Developer Mode](../chatgpt-developer-mode/)
-## 参考
+### 官方参考
-- [OpenAI Docs MCP](https://developers.openai.com/learn/docs-mcp)
+- [OpenAI Docs MCP](https://platform.openai.com/docs/docs-mcp)
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/codex.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/codex.en.md
index e82f04ca645..65a58a0a7d3 100644
---
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/codex.en.md
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/codex.en.md
@@ -3,7 +3,13 @@ title = "Codex"
weight = 1
+++
-This page explains how to connect Codex to an already running
ShardingSphere-MCP HTTP Server.
+This page explains how to connect Codex to an already running
ShardingSphere-MCP HTTP Server. ShardingSphere-MCP is the Apache ShardingSphere
MCP Server that exposes database metadata access, controlled SQL queries, and
database governance capabilities to MCP-capable AI clients and platforms.
+
+## Applicable Scenarios
+
+- Use this page when you want to connect an already running ShardingSphere-MCP
HTTP Server to Codex CLI or the Codex IDE extension.
+- Use this integration when Codex sessions need database metadata queries,
controlled read-only SQL queries, rule planning, or preflight validation.
+- After integration, Codex can inspect logic databases, inspect table
structures, run controlled read-only queries, or call
`database_gateway_validate_proxy_connectivity` for preflight validation.
## Prerequisites
@@ -11,7 +17,9 @@ This page explains how to connect Codex to an already running
ShardingSphere-MCP
- Codex CLI or the Codex IDE extension is available.
- The Codex environment can reach `http://127.0.0.1:18088/mcp`, or the actual
MCP Server address you configured.
-## Add the MCP Server
+## Integration Steps
+
+### Configure the integration
Use Codex CLI to add ShardingSphere-MCP:
@@ -34,17 +42,37 @@ url = "http://127.0.0.1:18088/mcp";
If the MCP Server address is not the default value, replace the URL with the
actual address.
-## Usage
+### Verify the integration
+
+Recognition succeeds when:
+
+- Run `codex mcp list` and confirm that `shardingsphere` appears in the MCP
Server list.
+
+Invocation succeeds when:
+
+- In a Codex session, run a minimal validation task such as:
+ - Show the tables in `<logic-database>`.
+ - Show columns and indexes for the `orders` table.
+ - Run `database_gateway_validate_proxy_connectivity` against a configured
runtime database.
+- If the tool list and query results are returned, the integration is working.
+
+## Notes
+
+- This page only covers connecting Codex to an already running HTTP MCP
Server. It does not cover starting a local `STDIO` process from Codex.
+- See the [Capability Catalog](../../capabilities/) for the supported task
surface and usage boundaries.
+- When SQL execution or rule changes are involved, review the preview content
before confirming execution.
+- If you want to integrate ShardingSphere-MCP through the OpenAI API or the
ChatGPT product UI, use the platform and API integration pages instead of
reusing the steps on this page.
-Describe database tasks directly in a Codex session, for example:
+## References
-- Show the tables in `<logic-database>`.
-- Show columns and indexes for the `orders` table.
-- Query the first 10 rows from the `orders` table.
-- Plan a masking rule for `orders.phone` and preview it without execution.
+### Related documents
-When SQL execution or rule changes are involved, review the preview content
before confirming execution.
+- [Quick Start](../../quick-start/)
+- [Capability Catalog](../../capabilities/)
+- [Configuration](../../configuration/)
+- [OpenAI Responses API](../openai-responses-api/)
+- [ChatGPT Developer Mode](../chatgpt-developer-mode/)
-## Reference
+### Official references
-- [OpenAI Docs MCP](https://developers.openai.com/learn/docs-mcp)
+- [Docs MCP](https://platform.openai.com/docs/docs-mcp)
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/openai-responses-api.cn.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/openai-responses-api.cn.md
new file mode 100644
index 00000000000..779d5d27ca1
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/openai-responses-api.cn.md
@@ -0,0 +1,104 @@
++++
+title = "OpenAI Responses API"
+weight = 3
++++
+
+本页说明如何在 OpenAI Responses API 中接入已经启动的 ShardingSphere-MCP HTTP
Server。ShardingSphere-MCP 是 Apache ShardingSphere 提供的 MCP Server，用于把数据库元数据访问、受控
SQL 查询和数据库治理能力暴露给支持 MCP 的 AI 客户端和平台。
+
+## 适用场景
+
+- 适合在后端服务、Agent 平台或自研应用中通过 OpenAI API 调用 ShardingSphere-MCP。
+- 适合在模型调用中按需导入 ShardingSphere-MCP 工具，并通过 `allowed_tools`、`require_approval` 或
OAuth 参数约束使用范围。
+- 接入完成后，可以让模型在 API 调用中查看逻辑库中的表、查看表结构、执行受控只读查询，或调用
`database_gateway_validate_proxy_connectivity` 对已经配置的 runtime database 进行接入前校验。
+
+## 前置条件
+
+- 已按[快速开始](../../quick-start/)启动 HTTP MCP Server。
+- 只暴露可被 OpenAI API 访问且已受保护的远程 endpoint。ShardingSphere-MCP 内置 HTTP Server
不提供认证或授权。
+- 远程平台接入时，应将 ShardingSphere-MCP 放在受信网关或反向代理后面，由外层组件提供 TLS 终止、身份认证、
+ 授权策略、网络访问控制和审计日志。
+ 安全边界见[部署说明](../../deployment/)和[配置说明](../../configuration/)。
+- 该受保护的远程 endpoint 需要支持 `Streamable HTTP` 或 `HTTP/SSE`。
+- 已准备 OpenAI API Key，并选择支持 remote MCP 的模型。
+- 如果受保护的远程 endpoint 或网关使用 OAuth 或 Bearer 认证，还需要准备可传给 MCP tool 的访问令牌。
+
+## 接入步骤
+
+### 配置接入
+
+在 Responses API 请求中，把 ShardingSphere-MCP 作为 `tools` 中的一个 `mcp` 工具传入。最小示例如下：
+
+```python
+from openai import OpenAI
+
+client = OpenAI()
+
+response = client.responses.create(
+ model="gpt-5",
+ tools=[
+ {
+ "type": "mcp",
+ "server_label": "shardingsphere",
+ "server_url": "https://example.com/mcp";,
+ "allowed_tools": [
+ "database_gateway_search_metadata",
+ "database_gateway_validate_proxy_connectivity",
+ ],
+ }
+ ],
+ input="Use ShardingSphere-MCP to inspect the tables in the logic
database.",
+)
+```
+
+配置时建议关注这些字段：
+
+- `server_label`：当前 MCP Server 的标识名称，后续工具调用和审批事件会引用这个名称。
+- `server_url`：位于 ShardingSphere-MCP 前方、已受保护的远程 HTTP 地址。
+- `allowed_tools`：可选。用于只导入 ShardingSphere-MCP 暴露工具中的一个子集，适合先从只读工具和预检工具开始。
+- `require_approval`：可选。默认会触发审批请求。只有在你已经审查过工具范围并接受自动调用时，才应关闭审批。
+- `authorization`：可选。仅当受保护的远程 endpoint 或网关需要 OAuth 或 Bearer 访问令牌时，在这里传入认证信息。
+ 该字段不会为 ShardingSphere-MCP 内置 HTTP Server 启用认证能力。
+
+### 验证接入成功
+
+识别成功：
+
+- 首次请求成功导入工具后，Responses API 会返回 `mcp_list_tools` 输出项。
+- 如果请求包含需要审批的 MCP tool call，Responses API 会返回 `mcp_approval_request` 输出项，此时需要按
OpenAI 审批流程补发 `mcp_approval_response`。
+
+调用成功：
+
+- 可以先用一条最小验证请求确认导入与调用链路，例如：
+ - 查看 `<logic-database>` 中有哪些表。
+ - 查看 `orders` 表的列和索引。
+ - 对已经配置的 runtime database 调用 `database_gateway_validate_proxy_connectivity`。
+- 当 `mcp_list_tools`、审批流程或最终查询结果按预期返回时，说明接入已经生效。
+
+如果接入失败，优先检查：
+
+- `server_url` 是否为 OpenAI 平台可访问且已受保护的远程地址，而不是本地 `127.0.0.1` 地址或直接暴露的未认证内置 HTTP
Server。
+- 工具导入阶段是否返回了 `mcp_list_tools`；如果没有，先排查远程地址和服务可用性。
+- 是否收到了 `mcp_approval_request`，以及后续是否正确补发了 `mcp_approval_response`。
+
+## 注意事项
+
+- OpenAI Responses API 的 remote MCP 只适用于远程 HTTP MCP Server，不适用于本地 `STDIO` 进程。
+- 远程 MCP Server 默认会触发审批流程。对于可能产生写操作或副作用的工具，应保留审批或显式限制 `allowed_tools`。
+- 只通过你信任的环境暴露 ShardingSphere-MCP，并优先使用受你控制的远程地址。
+- 本页只说明 OpenAI API 集成方式。若希望在 ChatGPT 产品界面中直接接入，请参考 [ChatGPT Developer
Mode](../chatgpt-developer-mode/)。
+- 具体可用任务和使用边界见[能力清单](../../capabilities/)。
+
+## 参考资料
+
+### 相关文档
+
+- [快速开始](../../quick-start/)
+- [能力清单](../../capabilities/)
+- [配置说明](../../configuration/)
+- [Codex](../codex/)
+- [ChatGPT Developer Mode](../chatgpt-developer-mode/)
+
+### 官方参考
+
+- [Connectors and MCP
servers](https://platform.openai.com/docs/guides/tools-remote-mcp)
+- [Responses API remote MCP
reference](https://platform.openai.com/docs/api-reference/responses/remote-mcp)
diff --git
a/docs/document/content/user-manual/shardingsphere-mcp/client-integration/openai-responses-api.en.md
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/openai-responses-api.en.md
new file mode 100644
index 00000000000..42a02096505
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-mcp/client-integration/openai-responses-api.en.md
@@ -0,0 +1,104 @@
++++
+title = "OpenAI Responses API"
+weight = 3
++++
+
+This page explains how to connect an already running ShardingSphere-MCP HTTP
Server to the OpenAI Responses API. ShardingSphere-MCP is the Apache
ShardingSphere MCP Server that exposes database metadata access, controlled SQL
queries, and database governance capabilities to MCP-capable AI clients and
platforms.
+
+## Applicable Scenarios
+
+- Use this page when a backend service, agent platform, or custom application
needs to call ShardingSphere-MCP through the OpenAI API.
+- Use this integration when the model should import ShardingSphere-MCP tools
on demand and constrain them with `allowed_tools`, `require_approval`, or OAuth
parameters.
+- After integration, the model can inspect logic databases, inspect table
structures, run controlled read-only queries, or call
`database_gateway_validate_proxy_connectivity` for preflight validation against
configured runtime databases.
+
+## Prerequisites
+
+- Start the HTTP MCP Server by following [Quick Start](../../quick-start/).
+- Expose only a secured remote endpoint that OpenAI API can reach. The
built-in ShardingSphere-MCP HTTP Server does not provide authentication or
authorization.
+- For remote platform access, place ShardingSphere-MCP behind a trusted
gateway or reverse proxy that provides TLS termination, authentication,
+ authorization policy, network access control, and audit logs.
+ See [Deployment](../../deployment/) and
[Configuration](../../configuration/) for the security boundary.
+- The secured remote endpoint must support `Streamable HTTP` or `HTTP/SSE`.
+- Prepare an OpenAI API key and choose a model that supports remote MCP.
+- If the secured remote endpoint or gateway requires OAuth or Bearer
authentication, prepare an access token that can be passed to the MCP tool.
+
+## Integration Steps
+
+### Configure the integration
+
+Pass ShardingSphere-MCP as an `mcp` tool in the `tools` array of a Responses
API request. A minimal example is:
+
+```python
+from openai import OpenAI
+
+client = OpenAI()
+
+response = client.responses.create(
+ model="gpt-5",
+ tools=[
+ {
+ "type": "mcp",
+ "server_label": "shardingsphere",
+ "server_url": "https://example.com/mcp";,
+ "allowed_tools": [
+ "database_gateway_search_metadata",
+ "database_gateway_validate_proxy_connectivity",
+ ],
+ }
+ ],
+ input="Use ShardingSphere-MCP to inspect the tables in the logic
database.",
+)
+```
+
+Pay attention to these fields:
+
+- `server_label`: the label used to identify this MCP server in tool calls and
approval events.
+- `server_url`: the secured remote HTTP address that fronts ShardingSphere-MCP.
+- `allowed_tools`: optional. Import only a subset of ShardingSphere-MCP tools,
which is useful when starting with read-only and validation tools.
+- `require_approval`: optional. Approval is required by default. Disable it
only after you have reviewed the tool surface and accept automatic tool calls.
+- `authorization`: optional. Pass authentication data here only when the
secured remote endpoint or gateway requires an OAuth or Bearer access token.
+ This does not enable authentication inside the built-in ShardingSphere-MCP
HTTP Server.
+
+### Verify the integration
+
+Recognition succeeds when:
+
+- When the tool import succeeds, the Responses API returns an `mcp_list_tools`
output item.
+- If a call requires approval, the Responses API returns an
`mcp_approval_request` output item. Reply with `mcp_approval_response` by
following the OpenAI approval flow.
+
+Invocation succeeds when:
+
+- Start with a minimal validation request such as:
+ - Show the tables in `<logic-database>`.
+ - Show columns and indexes for the `orders` table.
+ - Call `database_gateway_validate_proxy_connectivity` for a configured
runtime database.
+- When `mcp_list_tools`, approval flow events, or final query results appear
as expected, the integration is working.
+
+If the integration fails, check these items first:
+
+- Confirm that `server_url` is a secured endpoint reachable from OpenAI, not a
local `127.0.0.1` address or a directly exposed unauthenticated built-in HTTP
Server.
+- Confirm that the tool import step returns `mcp_list_tools`; if not, start
with the remote endpoint and server availability.
+- Confirm whether an `mcp_approval_request` was returned and whether the
matching `mcp_approval_response` was sent.
+
+## Notes
+
+- The OpenAI Responses API remote MCP tool works with remote HTTP MCP Servers.
It does not connect to local `STDIO` processes.
+- Remote MCP calls require approval by default. Keep approvals in place for
tools that can write data or cause side effects, or explicitly constrain the
surface with `allowed_tools`.
+- Only expose ShardingSphere-MCP through an environment you trust, and prefer
a server URL you control.
+- This page covers the OpenAI API integration path only. If you want to
connect ShardingSphere-MCP directly in the ChatGPT product UI, use [ChatGPT
Developer Mode](../chatgpt-developer-mode/).
+- See the [Capability Catalog](../../capabilities/) for the supported task
surface and usage boundaries.
+
+## References
+
+### Related documents
+
+- [Quick Start](../../quick-start/)
+- [Capability Catalog](../../capabilities/)
+- [Configuration](../../configuration/)
+- [Codex](../codex/)
+- [ChatGPT Developer Mode](../chatgpt-developer-mode/)
+
+### Official references
+
+- [Connectors and MCP
servers](https://platform.openai.com/docs/guides/tools-remote-mcp)
+- [Responses API remote MCP
reference](https://platform.openai.com/docs/api-reference/responses/remote-mcp)
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 7e3cf342cc6..41880c146e2 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.cn.md
@@ -9,18 +9,18 @@ weight = 7
## 问题列表
-| 现象 | 可能原因 | 处理方式 |
-| --- | --- | --- |
-| MCP Server 启动失败 | Java 版本、配置文件路径、发行包目录或 YAML 必填字段不正确。 | 查看启动终端和
`logs/mcp.log`；确认使用 Java 21 及以上版本，配置文件存在，发行包 `lib/` 目录完整，并且 `runtimeDatabases`
至少配置一项运行时数据库。 |
-| AI 应用无法连接 ShardingSphere-MCP | 传输方式、端口、端点路径、绑定地址或 AI 应用中的 MCP Server 配置不一致。
| 检查 `transport.type`、`port`、`endpointPath`、`bindHost`，并确认 AI 应用使用相同的连接地址。 |
-| HTTP 远程访问失败或请求被拒绝 | HTTP 绑定地址、Origin 请求头、反向代理、网关转发或会话归属配置不符合安全策略。 |
本机调试使用回环地址；远程访问放在受控网关或反向代理后面；检查网关是否转发了期望的请求头；详细原因看服务端日志。 |
-| STDIO 模式没有响应 | STDIO 被当作命令行交互入口，或 AI 应用没有正确拉起 MCP 进程。 | 由 AI 应用拉起
ShardingSphere-MCP；诊断信息看 stderr 或 `logs/mcp.log`。 |
-| 看不到数据库或逻辑库 | `runtimeDatabases` 中的名称不正确、连接失败、权限不足，或目标范围确实为空。 |
读取当前可见数据库；如果返回连接错误分类，按下方连接错误分类处理；确认账号拥有元数据读取权限。 |
-| 查不到表、列或索引 | 连接目标不同、模式或命名空间不正确、账号权限不足，或 Proxy 可见逻辑元数据与底层物理库不同。 | 先确认连接的是
ShardingSphere-Proxy 还是数据库直连，再检查模式、命名空间、账号权限和 Proxy 可见元数据。 |
-| 查询被拒绝 | SQL 不属于只读查询，或包含锁定读、修改数据、修改结构、修改权限、事务控制等副作用。 |
只读任务使用查询语句；涉及副作用的任务先要求预览变更，再确认是否执行。 |
-| 查询执行失败或结果被截断 | SQL 语法、目标对象、权限、返回行数或超时限制不正确。 |
先查看表结构；缩小查询条件、减少返回列、降低返回行数；必要时调整超时时间。 |
-| 副作用 SQL 无法执行 | 修改类 SQL 未经过预览和确认，或当前账号没有执行权限。 | 先预览变更
SQL，审查影响范围，再确认执行；权限问题需要管理员处理。 |
-| 规则变更计划或校验失败 | 连接目标不是
ShardingSphere-Proxy、目标列不可见、算法不可用、参数不足、规则未执行成功，或人工执行包尚未完成。 | 确认
`runtimeDatabases` 指向 Proxy 逻辑库；按功能插件文档补充规则目标、算法和参数；人工执行后再校验。 |
+| 现象 | 可能原因
| 处理方式
|
+|------------------------------|-------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|
+| MCP Server 启动失败 | Java 版本、配置文件路径、发行包目录或 YAML 必填字段不正确。
| 查看启动终端和 `logs/mcp.log`；确认使用 Java 21 及以上版本，配置文件存在，发行包
`lib/` 目录完整，并且 `runtimeDatabases` 至少配置一项运行时数据库。 |
+| AI 应用无法连接 ShardingSphere-MCP | 传输方式、端口、端点路径、绑定地址或 AI 应用中的 MCP Server 配置不一致。
| 检查 `transport.type`、`port`、`endpointPath`、`bindHost`，并确认
AI 应用使用相同的连接地址。 |
+| HTTP 远程访问失败或请求被拒绝 | HTTP 绑定地址、Origin 请求头、反向代理、网关转发或会话归属配置不符合安全策略。
| 本机调试使用回环地址；远程访问放在受控网关或反向代理后面；检查网关是否转发了期望的请求头；详细原因看服务端日志。
|
+| STDIO 模式没有响应 | STDIO 被当作命令行交互入口，或 AI 应用没有正确拉起 MCP 进程。
| 由 AI 应用拉起 ShardingSphere-MCP；诊断信息看 stderr 或
`logs/mcp.log`。 |
+| 看不到数据库或逻辑库 | `runtimeDatabases`
中的名称不正确、连接失败、权限不足，或目标范围确实为空。 |
读取当前可见数据库；如果返回连接错误分类，按下方连接错误分类处理；确认账号拥有元数据读取权限。
|
+| 查不到表、列或索引 | 连接目标不同、模式或命名空间不正确、账号权限不足，或 Proxy
可见逻辑元数据与底层物理库不同。 | 先确认连接的是 ShardingSphere-Proxy
还是数据库直连，再检查模式、命名空间、账号权限和 Proxy 可见元数据。 |
+| 查询被拒绝 | SQL 不属于只读查询，或包含锁定读、修改数据、修改结构、修改权限、事务控制等副作用。
| 只读任务使用查询语句；涉及副作用的任务先要求预览变更，再确认是否执行。
|
+| 查询执行失败或结果被截断 | SQL 语法、目标对象、权限、返回行数或超时限制不正确。
| 先查看表结构；缩小查询条件、减少返回列、降低返回行数；必要时调整超时时间。
|
+| 副作用 SQL 无法执行 | 修改类 SQL 未经过预览和确认，或当前账号没有执行权限。
| 先预览变更 SQL，审查影响范围，再确认执行；权限问题需要管理员处理。
|
+| 规则变更计划或校验失败 | 连接目标不是
ShardingSphere-Proxy、目标列不可见、算法不可用、参数不足、规则未执行成功，或人工执行包尚未完成。 | 确认
`runtimeDatabases` 指向 Proxy 逻辑库；按功能插件文档补充规则目标、算法和参数；人工执行后再校验。
|
补充说明：
@@ -35,39 +35,39 @@ weight = 7
当运行时数据库或 ShardingSphere-Proxy 连接失败时，MCP 响应会返回连接错误分类，用于帮助定位问题。分类只描述失败原因，不暴露
JDBC URL、密码、环境变量或堆栈信息。
-| 分类 | 含义 |
-| --- | --- |
-| `missing_jdbc_driver` | 未找到配置的 JDBC 驱动。 |
-| `authentication_failed` | 用户名或密码认证失败。 |
-| `authorization_failed` | 当前账号没有访问目标数据库或元数据的权限。 |
-| `connection_timeout` | 连接超时，通常需要检查地址、端口、网络或超时设置。 |
-| `invalid_configuration` | 运行时数据库配置不完整或不一致。 |
-| `database_unavailable` | 目标数据库或 ShardingSphere-Proxy 当前不可用。 |
-| `connection_failed` | 连接失败，但无法归类为更具体的原因。 |
-| `database_not_visible` | 指定数据库或逻辑库对当前连接不可见。 |
+| 分类 | 含义 |
+|-------------------------|------------------------------------|
+| `missing_jdbc_driver` | 未找到配置的 JDBC 驱动。 |
+| `authentication_failed` | 用户名或密码认证失败。 |
+| `authorization_failed` | 当前账号没有访问目标数据库或元数据的权限。 |
+| `connection_timeout` | 连接超时，通常需要检查地址、端口、网络或超时设置。 |
+| `invalid_configuration` | 运行时数据库配置不完整或不一致。 |
+| `database_unavailable` | 目标数据库或 ShardingSphere-Proxy 当前不可用。 |
+| `connection_failed` | 连接失败，但无法归类为更具体的原因。 |
+| `database_not_visible` | 指定数据库或逻辑库对当前连接不可见。 |
## 运行时保护
-| 保护项 | 含义 | 处理方式 |
-| --- | --- | --- |
-| 查询返回行数 | 默认最多返回 100 行，单次最多请求 5000 行。 | 查询结果被截断时，缩小查询条件、减少返回列或降低返回行数。 |
-| 查询超时 | 单次查询最大可请求 300000 毫秒超时。 | 超时后缩小查询范围，或在合理范围内调整超时时间。 |
-| 工具调用次数 | 当前 MCP 会话达到工具调用次数保护限制时，会返回 `tool_call_limit_exceeded`。 |
结束当前会话并重新创建 MCP 会话。 |
-| 副作用执行 | 修改数据、结构、规则、权限或事务状态前需要预览和确认。 | 先审查预览内容，再决定是否执行。 |
+| 保护项 | 含义 | 处理方式
|
+|--------|--------------------------------------------------------|-------------------------------|
+| 查询返回行数 | 默认最多返回 100 行，单次最多请求 5000 行。 |
查询结果被截断时，缩小查询条件、减少返回列或降低返回行数。 |
+| 查询超时 | 单次查询最大可请求 300000 毫秒超时。 |
超时后缩小查询范围，或在合理范围内调整超时时间。 |
+| 工具调用次数 | 当前 MCP 会话达到工具调用次数保护限制时，会返回 `tool_call_limit_exceeded`。 |
结束当前会话并重新创建 MCP 会话。 |
+| 副作用执行 | 修改数据、结构、规则、权限或事务状态前需要预览和确认。 |
先审查预览内容，再决定是否执行。 |
## 后续代码改进项
以下内容记录当前文档已明确但仍需要后续源码演进的点。代码完成前，用户仍以现有工具名、错误分类和运行时行为为准。
-| 改进项 | 原因 | 建议 |
-| --- | --- | --- |
-| 连接预检工具命名 | 现有工具名 `database_gateway_validate_proxy_connectivity` 容易让用户误以为只能校验
Proxy，但实际校验的是已配置的运行时数据库连接。 | 后续改为更中性的名称，例如
`database_gateway_validate_runtime_database` 或
`database_gateway_validate_connectivity`，并同步调整描述符、测试和文档。 |
-| 运行状态中的错误分类 | 连接错误分类包含 `database_not_visible`，但运行状态资源的安全分类列表尚未完全对齐。 |
后续在运行状态资源中补齐该分类，保证排障分类和运行时状态一致。 |
-| HTTP 安全错误分类 | Origin 请求头和会话归属不一致时，目前主要通过 HTTP 状态码和日志定位。 | 后续增加稳定、非敏感的错误分类，例如
`origin_not_allowed` 和 `session_attribution_mismatch`，方便 AI 应用和管理员按错误码排查。 |
-| 空 `runtimeDatabases` 启动策略 | 当前启动配置要求 `runtimeDatabases` 非空，缺失或为空会导致启动校验失败。 |
如果后续希望支持先启动 Server 再补充运行时数据库，需要调整 YAML
校验、运行状态、启动日志和文档；如果仍要求非空，则保持当前启动失败行为，并继续让错误信息指向配置修正。 |
-| 查询失败错误分类 | 查询失败可能来自 SQL 语法、对象不存在、权限不足、连接中断或超时，目前用户仍需要结合错误响应和日志判断。 |
后续为查询执行失败补充稳定、非敏感的分类和处理建议，例如语法错误、对象不可见、权限不足和执行超时，并避免暴露原始连接信息或堆栈。 |
-| 元数据不可见错误分类 | 看不到数据库、模式、表、列或索引时，用户需要从配置、权限和连接目标中自行排查。 |
后续在元数据读取和搜索结果中返回更细的可见性分类，例如数据库不可见、模式不可见、对象不可见或权限不足，并给出下一步检查项。 |
-| 敏感值引用机制 | 规则变更可能需要密钥或凭证，目前由外部受控通道传递。 | 后续如需内置支持，应设计密钥引用或解析机制，而不是让 MCP Server
直接暴露敏感值。 |
+| 改进项 | 原因
| 建议
|
+|---------------------------|----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
+| 连接预检工具命名 | 现有工具名
`database_gateway_validate_proxy_connectivity` 容易让用户误以为只能校验
Proxy，但实际校验的是已配置的运行时数据库连接。 | 后续改为更中性的名称，例如
`database_gateway_validate_runtime_database` 或
`database_gateway_validate_connectivity`，并同步调整描述符、测试和文档。 |
+| 运行状态中的错误分类 | 连接错误分类包含
`database_not_visible`，但运行状态资源的安全分类列表尚未完全对齐。
| 后续在运行状态资源中补齐该分类，保证排障分类和运行时状态一致。
|
+| HTTP 安全错误分类 | Origin 请求头和会话归属不一致时，目前主要通过 HTTP 状态码和日志定位。
| 后续增加稳定、非敏感的错误分类，例如
`origin_not_allowed` 和 `session_attribution_mismatch`，方便 AI 应用和管理员按错误码排查。
|
+| 空 `runtimeDatabases` 启动策略 | 当前启动配置要求 `runtimeDatabases` 非空，缺失或为空会导致启动校验失败。
| 如果后续希望支持先启动 Server 再补充运行时数据库，需要调整
YAML 校验、运行状态、启动日志和文档；如果仍要求非空，则保持当前启动失败行为，并继续让错误信息指向配置修正。
|
+| 查询失败错误分类 | 查询失败可能来自 SQL
语法、对象不存在、权限不足、连接中断或超时，目前用户仍需要结合错误响应和日志判断。
| 后续为查询执行失败补充稳定、非敏感的分类和处理建议，例如语法错误、对象不可见、权限不足和执行超时，并避免暴露原始连接信息或堆栈。
|
+| 元数据不可见错误分类 | 看不到数据库、模式、表、列或索引时，用户需要从配置、权限和连接目标中自行排查。
|
后续在元数据读取和搜索结果中返回更细的可见性分类，例如数据库不可见、模式不可见、对象不可见或权限不足，并给出下一步检查项。
|
+| 敏感值引用机制 | 规则变更可能需要密钥或凭证，目前由外部受控通道传递。
| 后续如需内置支持，应设计密钥引用或解析机制，而不是让 MCP
Server 直接暴露敏感值。
|
## 提供给管理员或排障人员的信息
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 e4a734221c0..9f06e6ea764 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/troubleshooting.en.md
@@ -9,18 +9,18 @@ When troubleshooting, distinguish external environment issues
from MCP protectio
## Issue List
-| Symptom | Possible cause | Action |
-| --- | --- | --- |
-| MCP Server startup failure | Java version, config file path, distribution
directory, or required YAML field is wrong. | Inspect the startup terminal and
`logs/mcp.log`; use Java 21 or later, confirm that the config file exists,
ensure that the distribution `lib/` directory is complete, and configure at
least one runtime database in `runtimeDatabases`. |
-| The AI application cannot connect to ShardingSphere-MCP | Transport type,
port, endpoint path, bind address, or the MCP Server configuration in the AI
application is inconsistent. | Check `transport.type`, `port`, `endpointPath`,
`bindHost`, and the address configured in the AI application. |
-| Remote HTTP access fails or the HTTP request is rejected | HTTP bind
address, Origin header, reverse proxy, gateway forwarding, or session
attribution configuration does not satisfy the security policy. | Use loopback
for local debugging; place remote access behind a controlled gateway or reverse
proxy; check whether the gateway forwards the expected headers; inspect server
logs for details. |
-| No response in STDIO mode | STDIO is used as an interactive command-line
entry, or the AI application does not launch the MCP process correctly. | Let
the AI application launch ShardingSphere-MCP; inspect stderr or `logs/mcp.log`
for diagnostics. |
-| Databases or logical databases are not visible | The name in
`runtimeDatabases` is wrong, connection failed, privileges are insufficient, or
the target scope is empty. | Read the currently visible databases; if a
connection failure category is returned, follow the connection failure table
below; confirm that the account can read metadata. |
-| Tables, columns, or indexes cannot be found | The connection target is
different, schema or namespace 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, namespace, account privileges, and
Proxy-visible metadata. |
-| Query is rejected | The SQL is not read-only, or it contains locking reads,
data changes, schema changes, privilege changes, or transaction control. | Use
query statements for read-only tasks. For side-effecting tasks, preview the
change first and then decide whether to execute it. |
-| Query execution fails or the result is truncated | SQL syntax, target
object, privilege, row limit, or timeout limit is wrong. | Inspect table
structure first; narrow the predicate, reduce the projection, request fewer
rows, or adjust timeout within the supported range. |
-| Side-effecting SQL cannot be executed | The change SQL was not previewed and
confirmed, or the current account lacks execution privileges. | Preview the
change SQL, review the impact, and then confirm execution; privilege issues
require administrator action. |
-| Rule change planning or validation fails | The target is not
ShardingSphere-Proxy, the target column is not visible, the algorithm is
unavailable, required parameters are missing, the rule was not applied
successfully, or a manual package has not been executed. | Ensure that
`runtimeDatabases` points to a Proxy logical database; provide the rule target,
algorithm, and parameters according to the feature plugin documentation;
validate again after manual execution is completed. |
+| Symptom | Possible cause
| Action
[...]
+|----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+| MCP Server startup failure | Java version,
config file path, distribution directory, or required YAML field is wrong.
| Inspect the startup terminal and
`logs/mcp.log`; use Java 21 or later, confirm that the config file exists,
ensure that the distribution `lib/` directory is complete, and configure at
least one runtime database [...]
+| The AI application cannot connect to ShardingSphere-MCP | Transport type,
port, endpoint path, bind address, or the MCP Server configuration in the AI
application is inconsistent.
| Check `transport.type`, `port`,
`endpointPath`, `bindHost`, and the address configured in the AI application.
[...]
+| Remote HTTP access fails or the HTTP request is rejected | HTTP bind
address, Origin header, reverse proxy, gateway forwarding, or session
attribution configuration does not satisfy the security policy.
| Use loopback for
local debugging; place remote access behind a controlled gateway or reverse
proxy; check whether the gateway forwards the expected headers; inspect server
logs for details. [...]
+| No response in STDIO mode | STDIO is used as
an interactive command-line entry, or the AI application does not launch the
MCP process correctly.
| Let the AI application launch
ShardingSphere-MCP; inspect stderr or `logs/mcp.log` for diagnostics.
[...]
+| Databases or logical databases are not visible | The name in
`runtimeDatabases` is wrong, connection failed, privileges are insufficient, or
the target scope is empty.
| Read the currently visible
databases; if a connection failure category is returned, follow the connection
failure table below; confirm that the account can read metadata.
[...]
+| Tables, columns, or indexes cannot be found | The connection
target is different, schema or namespace 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, namespace, account privileges, and Proxy-visible metadata.
[...]
+| Query is rejected | The SQL is not
read-only, or it contains locking reads, data changes, schema changes,
privilege changes, or transaction control.
| Use query statements for
read-only tasks. For side-effecting tasks, preview the change first and then
decide whether to execute it.
[...]
+| Query execution fails or the result is truncated | SQL syntax,
target object, privilege, row limit, or timeout limit is wrong.
| Inspect table structure first;
narrow the predicate, reduce the projection, request fewer rows, or adjust
timeout within the supported range.
[...]
+| Side-effecting SQL cannot be executed | The change SQL
was not previewed and confirmed, or the current account lacks execution
privileges.
| Preview the change SQL,
review the impact, and then confirm execution; privilege issues require
administrator action.
[...]
+| Rule change planning or validation fails | The target is not
ShardingSphere-Proxy, the target column is not visible, the algorithm is
unavailable, required parameters are missing, the rule was not applied
successfully, or a manual package has not been executed. | Ensure that
`runtimeDatabases` points to a Proxy logical database; provide the rule target,
algorithm, and parameters according to the feature plugin documentation;
validate again after manual execution is comp [...]
Additional notes:
@@ -35,39 +35,39 @@ Additional notes:
When a runtime database or ShardingSphere-Proxy connection fails, MCP
responses return a connection failure category to help locate the issue.
Categories describe the failure cause without exposing JDBC URLs, passwords,
environment variables, or stack traces.
-| Category | Meaning |
-| --- | --- |
-| `missing_jdbc_driver` | The configured JDBC driver cannot be found. |
-| `authentication_failed` | Username or password authentication failed. |
-| `authorization_failed` | The current account does not have permission to
access the target database or metadata. |
-| `connection_timeout` | The connection timed out. Check the address, port,
network, or timeout settings. |
-| `invalid_configuration` | Runtime database configuration is incomplete or
inconsistent. |
-| `database_unavailable` | The target database or ShardingSphere-Proxy is
currently unavailable. |
-| `connection_failed` | The connection failed, but cannot be classified into a
more specific cause. |
-| `database_not_visible` | The specified database or logical database is not
visible to the current connection. |
+| Category | Meaning
|
+|-------------------------|-----------------------------------------------------------------------------------------|
+| `missing_jdbc_driver` | The configured JDBC driver cannot be found.
|
+| `authentication_failed` | Username or password authentication failed.
|
+| `authorization_failed` | The current account does not have permission to
access the target database or metadata. |
+| `connection_timeout` | The connection timed out. Check the address, port,
network, or timeout settings. |
+| `invalid_configuration` | Runtime database configuration is incomplete or
inconsistent. |
+| `database_unavailable` | The target database or ShardingSphere-Proxy is
currently unavailable. |
+| `connection_failed` | The connection failed, but cannot be classified
into a more specific cause. |
+| `database_not_visible` | The specified database or logical database is not
visible to the current connection. |
## Runtime Protection
-| Protection | Meaning | Action |
-| --- | --- | --- |
-| Query row limit | Queries return at most 100 rows by default, and one query
can request at most 5000 rows. | When a result is truncated, narrow the
predicate, reduce the projection, or request fewer rows. |
-| Query timeout | One query can request at most 300000 milliseconds as the
timeout. | After a timeout, narrow the query scope or adjust timeout within the
supported range. |
-| Tool-call quota | When the current MCP session reaches the tool-call
protection limit, MCP returns `tool_call_limit_exceeded`. | Close the current
session and create a new MCP session. |
-| Side-effect execution | Data, schema, rule, privilege, or transaction-state
changes require preview and confirmation before execution. | Review the preview
before deciding whether to execute. |
+| Protection | Meaning
| Action
|
+|-----------------------|----------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|
+| Query row limit | Queries return at most 100 rows by default, and one
query can request at most 5000 rows. | When a result is
truncated, narrow the predicate, reduce the projection, or request fewer rows. |
+| Query timeout | One query can request at most 300000 milliseconds as
the timeout. | After a timeout,
narrow the query scope or adjust timeout within the supported range. |
+| Tool-call quota | When the current MCP session reaches the tool-call
protection limit, MCP returns `tool_call_limit_exceeded`. | Close the current
session and create a new MCP session. |
+| Side-effect execution | Data, schema, rule, privilege, or transaction-state
changes require preview and confirmation before execution. | Review the preview
before deciding whether to execute. |
## Future Code Improvements
The following items are documented as known follow-up code improvements. Until
the code changes are completed, users should rely on the current tool names,
error categories, and runtime behavior.
-| Improvement | Reason | Recommendation |
-| --- | --- | --- |
-| Connectivity validation tool name | The current tool name
`database_gateway_validate_proxy_connectivity` can imply that only Proxy is
validated, but the tool actually validates a configured runtime database
connection. | Rename it to a more neutral name, such as
`database_gateway_validate_runtime_database` or
`database_gateway_validate_connectivity`, and update descriptors, tests, and
documentation together. |
-| Error categories in runtime status | The connection failure categories
include `database_not_visible`, but the safe category list in the runtime
status resource is not fully aligned. | Add this category to the runtime status
resource so troubleshooting categories and runtime status stay consistent. |
-| HTTP security error categories | Origin header and session attribution
failures are currently located mainly through HTTP status codes and logs. | Add
stable, non-sensitive error categories such as `origin_not_allowed` and
`session_attribution_mismatch`, so AI applications and administrators can
troubleshoot by category. |
-| Empty `runtimeDatabases` startup policy | The current launch configuration
requires `runtimeDatabases` to be non-empty. A missing or empty value fails
startup validation. | If startup without runtime databases should be supported
later, adjust YAML validation, runtime status, startup logs, and documentation
together. If the non-empty requirement remains, keep startup failure behavior
and continue directing users to fix the configuration. |
-| Query failure error categories | Query failures can come from SQL syntax,
invisible objects, insufficient privileges, interrupted connections, or
timeout. Users currently need to combine the error response with logs to
identify the cause. | Add stable, non-sensitive categories and actions for
query execution failures, such as syntax error, object not visible,
insufficient privileges, and execution timeout, without exposing raw connection
details or stack traces. |
-| Metadata visibility error categories | When databases, schemas, tables,
columns, or indexes are not visible, users need to inspect configuration,
privileges, and connection target manually. | Return finer-grained visibility
categories from metadata read and search results, such as database not visible,
schema not visible, object not visible, or insufficient privileges, with the
next checks to perform. |
-| Secret reference mechanism | Rule changes may require keys or credentials,
which are currently passed through external protected channels. | If built-in
support is required later, design a secret reference or resolver mechanism
instead of exposing sensitive values through the MCP Server. |
+| Improvement | Reason
| Recommendation
[...]
+|-----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+| Connectivity validation tool name | The current tool name
`database_gateway_validate_proxy_connectivity` can imply that only Proxy is
validated, but the tool actually validates a configured runtime database
connection. | Rename it to a more neutral name, such as
`database_gateway_validate_runtime_database` or
`database_gateway_validate_connectivity`, and update descriptors, tests, and
documentation together. [...]
+| Error categories in runtime status | The connection failure categories
include `database_not_visible`, but the safe category list in the runtime
status resource is not fully aligned.
| Add this category to the runtime status resource so
troubleshooting categories and runtime status stay consistent.
[...]
+| HTTP security error categories | Origin header and session
attribution failures are currently located mainly through HTTP status codes and
logs.
| Add stable, non-sensitive error categories such as
`origin_not_allowed` and `session_attribution_mismatch`, so AI applications and
administrators can troubleshoot by category.
[...]
+| Empty `runtimeDatabases` startup policy | The current launch configuration
requires `runtimeDatabases` to be non-empty. A missing or empty value fails
startup validation.
| If startup without runtime databases should be supported
later, adjust YAML validation, runtime status, startup logs, and documentation
together. If the non-empty requirement remains, keep startup failure behavior
and continue directing use [...]
+| Query failure error categories | Query failures can come from SQL
syntax, invisible objects, insufficient privileges, interrupted connections, or
timeout. Users currently need to combine the error response with logs to
identify the cause. | Add stable, non-sensitive categories and actions for
query execution failures, such as syntax error, object not visible,
insufficient privileges, and execution timeout, without exposing raw connection
details or stack traces. [...]
+| Metadata visibility error categories | When databases, schemas, tables,
columns, or indexes are not visible, users need to inspect configuration,
privileges, and connection target manually.
| Return finer-grained visibility categories from metadata
read and search results, such as database not visible, schema not visible,
object not visible, or insufficient privileges, with the next checks to
perform. [...]
+| Secret reference mechanism | Rule changes may require keys or
credentials, which are currently passed through external protected channels.
| If built-in support is required later, design a secret reference
or resolver mechanism instead of exposing sensitive values through the MCP
Server.
[...]
## Information for Administrators or Troubleshooters
