OpenAI Responses API
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_runtime_databasefor preflight validation against configured runtime databases.
Prerequisites
- Start the HTTP MCP Server by following 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 and Configuration for the security boundary.
- The secured remote endpoint must support
Streamable HTTPorHTTP/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:
import os
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-5",
tools=[
{
"type": "mcp",
"server_label": "shardingsphere",
"server_url": os.environ["SHARDINGSPHERE_MCP_REMOTE_URL"],
"allowed_tools": [
"database_gateway_search_metadata",
"database_gateway_validate_runtime_database",
],
}
],
input="Use ShardingSphere-MCP to inspect the tables in the logic database.",
)Set SHARDINGSPHERE_MCP_REMOTE_URL to the secured remote endpoint published by the trusted gateway before running the request.
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_toolsoutput item. - If a call requires approval, the Responses API returns an
mcp_approval_requestoutput item. Reply withmcp_approval_responseby following the OpenAI approval flow.
Invocation succeeds when:
- Start with a minimal validation request such as:
- Show the tables in
logic_db. - Show columns and indexes for the
orderstable. - Call
database_gateway_validate_runtime_databasefor a configured runtime database.
- Show the tables in
- 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_urlis a secured endpoint reachable from OpenAI, not a local127.0.0.1address 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_requestwas returned and whether the matchingmcp_approval_responsewas sent.
Notes
- The OpenAI Responses API remote MCP tool works with remote HTTP MCP Servers. It does not connect to local
STDIOprocesses. - 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.
- See the Capability Catalog for the supported task surface and usage boundaries.