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 1e934a2f99e Add trusted gateway deployment examples for MCP (#38808)
1e934a2f99e is described below
commit 1e934a2f99e9ff5d9d4d2ebedda05ef8a13e852e
Author: Liang Zhang <[email protected]>
AuthorDate: Thu Jun 4 23:33:37 2026 +0800
Add trusted gateway deployment examples for MCP (#38808)
* Add trusted gateway deployment examples for MCP
Extend the ShardingSphere-MCP deployment guide with platform-agnostic
examples for trusted gateway placement, TLS termination, and session
attribution header wiring.
Document the minimal ShardingSphere-MCP configuration, a reverse proxy
example, the expected attribution headers, and the key deployment rules
for safe remote exposure.
* Add trusted gateway deployment examples for MCP
Extend the ShardingSphere-MCP deployment guide with platform-agnostic
examples for trusted gateway placement, TLS termination, and session
attribution header wiring.
Document the minimal ShardingSphere-MCP configuration, a reverse proxy
example, the expected attribution headers, and the key deployment rules
for safe remote exposure.
---
.../shardingsphere-mcp/deployment.cn.md | 92 ++++++++++++++++++++++
.../shardingsphere-mcp/deployment.en.md | 92 ++++++++++++++++++++++
2 files changed, 184 insertions(+)
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 b3f0d53b684..a1dfc05a59e 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/deployment.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/deployment.cn.md
@@ -94,6 +94,98 @@ HTTP 绑定建议：
- 面向远程客户端暴露时，避免直接裸露 MCP Server。
- 需要把会话和外部用户或调用来源关联时，由受信网关注入会话归属请求头；不要允许客户端直接伪造这些请求头。
+### 受信网关与 TLS 终止样例
+
+以下示例使用 Nginx 说明“外层入口负责 HTTPS，ShardingSphere-MCP 继续在受控网络中提供
HTTP”的最小布局。其他反向代理、Ingress、ALB 或 API Gateway 只要满足同样边界，也可以采用相同思路。
+
+ShardingSphere-MCP 配置示例：
+
+```yaml
+transport:
+ type: STREAMABLE_HTTP
+ http:
+ bindHost: 127.0.0.1
+ port: 18088
+ endpointPath: /mcp
+ sessionAttributionSource:
+ subjectHeader: X-ShardingSphere-MCP-Subject
+ sourceHeader: X-ShardingSphere-MCP-Source
+ attributeHeaderPrefix: X-ShardingSphere-MCP-Attribute-
+```
+
+Nginx 示例：
+
+```nginx
+server {
+ listen 443 ssl http2;
+ server_name mcp.example.com;
+
+ ssl_certificate /etc/nginx/certs/mcp.crt;
+ ssl_certificate_key /etc/nginx/certs/mcp.key;
+
+ location /mcp {
+ proxy_pass http://127.0.0.1:18088/mcp;
+ proxy_http_version 1.1;
+ proxy_pass_request_headers off;
+
+ proxy_set_header Host $host;
+ proxy_set_header Content-Type $http_content_type;
+ proxy_set_header Accept $http_accept;
+ proxy_set_header MCP-Session-Id $http_mcp_session_id;
+ proxy_set_header MCP-Protocol-Version $http_mcp_protocol_version;
+ proxy_set_header X-Forwarded-Proto https;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ }
+}
+```
+
+这类布局的关键点是：
+
+- TLS 在受信网关终止，MCP 进程本身不直接管理公网证书。
+- ShardingSphere-MCP 继续绑定到本地回环地址或受控内网接口，不直接裸露到公网。
+- 认证、授权、限流和网络访问控制仍由外层网关处理，而不是由内置 HTTP Server 处理。
+
+### 会话归属接线样例
+
+如果外层网关已经能识别调用方身份，可以让网关在转发请求时覆写会话归属请求头，再由 MCP Runtime
绑定到会话上下文。请求头名称与前缀应和[配置说明](../configuration/)中的
`transport.http.sessionAttributionSource` 保持一致。
+
+Nginx 示例：
+
+```nginx
+location /mcp {
+ proxy_pass http://127.0.0.1:18088/mcp;
+ proxy_http_version 1.1;
+ proxy_pass_request_headers off;
+
+ proxy_set_header Host $host;
+ proxy_set_header Content-Type $http_content_type;
+ proxy_set_header Accept $http_accept;
+ proxy_set_header MCP-Session-Id $http_mcp_session_id;
+ proxy_set_header MCP-Protocol-Version $http_mcp_protocol_version;
+ proxy_set_header X-Forwarded-Proto https;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+
+ proxy_set_header X-ShardingSphere-MCP-Subject $remote_user;
+ proxy_set_header X-ShardingSphere-MCP-Source gateway-nginx;
+ proxy_set_header X-ShardingSphere-MCP-Attribute-Environment production;
+}
+```
+
+接线时建议遵循以下原则：
+
+- 对转发到后端的请求头使用白名单，或在注入可信值前剥离或拒绝所有匹配归属请求头名称和前缀的客户端原始请求头。
+- `subjectHeader` 表示外部主体，例如试用账号、正式客户标识或内部调用身份。
+- `sourceHeader` 表示请求来源，例如 `gateway-nginx`、`internal-alb` 或其他受信入口名称。
+- `attributeHeaderPrefix` 可用于注入少量非敏感上下文，例如环境、区域或接入渠道；不要通过这些请求头传递密码、密钥或令牌。
+- 如果当前部署不需要把请求归属绑定到会话上下文，可以省略 `sessionAttributionSource` 配置。
+
+完成接线后，继续按照下文的健康检查步骤确认：
+
+- 网关地址可访问。
+- MCP 协议已就绪。
+- 运行时数据库已就绪。
+- 同一会话内的后续请求不会因为归属请求头变化而失配。
+
## 健康检查
部署完成后，建议按以下顺序确认 ShardingSphere-MCP 是否真正可用，而不只停留在“HTTP 端口可达”：
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 c3f96cbcf38..8574c0a1429 100644
--- a/docs/document/content/user-manual/shardingsphere-mcp/deployment.en.md
+++ b/docs/document/content/user-manual/shardingsphere-mcp/deployment.en.md
@@ -94,6 +94,98 @@ HTTP binding recommendations:
- 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.
+### Trusted gateway and TLS termination example
+
+The following example uses Nginx to illustrate the minimum layout in which the
outer entry handles HTTPS while ShardingSphere-MCP continues to serve plain
HTTP on a controlled network interface. Other reverse proxies, ingress
controllers, ALBs, or API gateways can follow the same boundary.
+
+ShardingSphere-MCP configuration example:
+
+```yaml
+transport:
+ type: STREAMABLE_HTTP
+ http:
+ bindHost: 127.0.0.1
+ port: 18088
+ endpointPath: /mcp
+ sessionAttributionSource:
+ subjectHeader: X-ShardingSphere-MCP-Subject
+ sourceHeader: X-ShardingSphere-MCP-Source
+ attributeHeaderPrefix: X-ShardingSphere-MCP-Attribute-
+```
+
+Nginx example:
+
+```nginx
+server {
+ listen 443 ssl http2;
+ server_name mcp.example.com;
+
+ ssl_certificate /etc/nginx/certs/mcp.crt;
+ ssl_certificate_key /etc/nginx/certs/mcp.key;
+
+ location /mcp {
+ proxy_pass http://127.0.0.1:18088/mcp;
+ proxy_http_version 1.1;
+ proxy_pass_request_headers off;
+
+ proxy_set_header Host $host;
+ proxy_set_header Content-Type $http_content_type;
+ proxy_set_header Accept $http_accept;
+ proxy_set_header MCP-Session-Id $http_mcp_session_id;
+ proxy_set_header MCP-Protocol-Version $http_mcp_protocol_version;
+ proxy_set_header X-Forwarded-Proto https;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ }
+}
+```
+
+The important points of this layout are:
+
+- TLS terminates at the trusted gateway, so the MCP process does not manage
public certificates directly.
+- ShardingSphere-MCP continues to bind to loopback or a controlled intranet
interface instead of being exposed directly to the public network.
+- Authentication, authorization, rate limiting, and network access control
remain the responsibility of the outer gateway, not the built-in HTTP Server.
+
+### Session attribution wiring example
+
+When the outer gateway already identifies the caller, let it overwrite the
session attribution headers before forwarding the request. The MCP Runtime then
binds the resulting attribution to the session context. Keep the header names
and prefix aligned with `transport.http.sessionAttributionSource` in the
[Configuration](../configuration/) document.
+
+Nginx example:
+
+```nginx
+location /mcp {
+ proxy_pass http://127.0.0.1:18088/mcp;
+ proxy_http_version 1.1;
+ proxy_pass_request_headers off;
+
+ proxy_set_header Host $host;
+ proxy_set_header Content-Type $http_content_type;
+ proxy_set_header Accept $http_accept;
+ proxy_set_header MCP-Session-Id $http_mcp_session_id;
+ proxy_set_header MCP-Protocol-Version $http_mcp_protocol_version;
+ proxy_set_header X-Forwarded-Proto https;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+
+ proxy_set_header X-ShardingSphere-MCP-Subject $remote_user;
+ proxy_set_header X-ShardingSphere-MCP-Source gateway-nginx;
+ proxy_set_header X-ShardingSphere-MCP-Attribute-Environment production;
+}
+```
+
+Follow these rules when wiring attribution:
+
+- Use an allow-list for proxied request headers, or strip/reject every
client-supplied header that matches the configured attribution header names and
prefix before injecting trusted values.
+- `subjectHeader` represents the external subject, such as a trial user, a
commercial customer identifier, or an internal caller identity.
+- `sourceHeader` identifies the request source, such as `gateway-nginx`,
`internal-alb`, or another trusted ingress name.
+- `attributeHeaderPrefix` can carry a small amount of non-sensitive context
such as environment, region, or integration channel; do not pass passwords,
keys, or tokens through these headers.
+- If the deployment does not need to bind request attribution into the session
context, omit `sessionAttributionSource`.
+
+After wiring the gateway, continue with the health checks below to confirm
that:
+
+- The gateway endpoint is reachable.
+- The MCP protocol is ready.
+- Runtime databases are ready.
+- Later requests in the same session do not fail because the attribution
headers change.
+
## Health Checks
After deployment, verify that ShardingSphere-MCP is truly usable instead of
stopping at “the HTTP port is reachable”:
