6.0 KiB

Raw Blame History

ProxySQL MCP stdio Bridge

A bridge that converts between stdio-based MCP (for Claude Code) and ProxySQL's HTTPS MCP endpoint.

What It Does

┌─────────────┐     stdio      ┌──────────────────┐     HTTPS      ┌──────────┐
│  Claude Code│  ──────────>  │  stdio Bridge    │  ──────────>  │ ProxySQL │
│  (MCP Client)│               │  (this script)   │               │  MCP     │
└─────────────┘               └──────────────────┘               └──────────┘

To Claude Code: Acts as an MCP Server (stdio transport)
To ProxySQL: Acts as an MCP Client (HTTPS transport)

Installation

Install dependencies:

pip install httpx

Make the script executable:

chmod +x proxysql_mcp_stdio_bridge.py

Configuration

Environment Variables

Variable	Required	Default	Description
`PROXYSQL_MCP_ENDPOINT`	No	`https://127.0.0.1:6071/mcp/query`	ProxySQL MCP endpoint URL
`PROXYSQL_MCP_TOKEN`	No	-	Bearer token for authentication (if configured)
`PROXYSQL_MCP_INSECURE_SSL`	No	0	Set to 1 to disable SSL verification (for self-signed certs)

Configure in Claude Code

Add to your Claude Code MCP settings (usually ~/.config/claude-code/mcp_config.json or similar):

{
  "mcpServers": {
    "proxysql": {
      "command": "python3",
      "args": ["./scripts/mcp/proxysql_mcp_stdio_bridge.py"],
      "env": {
        "PROXYSQL_MCP_ENDPOINT": "https://127.0.0.1:6071/mcp/query",
        "PROXYSQL_MCP_TOKEN": "your_token_here",
        "PROXYSQL_MCP_INSECURE_SSL": "1"
      }
    }
  }
}

Quick Test from Terminal

export PROXYSQL_MCP_ENDPOINT="https://127.0.0.1:6071/mcp/query"
export PROXYSQL_MCP_TOKEN="your_token"  # optional
export PROXYSQL_MCP_INSECURE_SSL="1"   # for self-signed certs

python3 proxysql_mcp_stdio_bridge.py

Then send a JSON-RPC request via stdin:

{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}

Supported MCP Methods

Method	Description
`initialize`	Handshake protocol
`tools/list`	List available ProxySQL MCP tools
`tools/call`	Call a ProxySQL MCP tool
`ping`	Health check

Available Tools (from ProxySQL)

Once connected, the following tools will be available in Claude Code:

Database Exploration Tools

list_schemas - List databases
list_tables - List tables in a schema
describe_table - Get table structure
get_constraints - Get foreign keys and constraints
sample_rows - Sample data from a table
run_sql_readonly - Execute read-only SQL queries
explain_sql - Get query execution plan
table_profile - Get table statistics
column_profile - Get column statistics
suggest_joins - Suggest join paths between tables
find_reference_candidates - Find potential foreign key relationships

Two-Phase Discovery Tools

discovery.run_static - Run Phase 1 of two-phase discovery (static harvest)
agent.run_start - Start a new agent run for discovery coordination
agent.run_finish - Mark an agent run as completed
agent.event_append - Append an event to an agent run

LLM Interaction Tools

llm.summary_upsert - Store or update a table/column summary generated by LLM
llm.summary_get - Retrieve LLM-generated summary for a table or column
llm.relationship_upsert - Store or update an inferred relationship between tables
llm.domain_upsert - Store or update a business domain classification
llm.domain_set_members - Set the members (tables) of a business domain
llm.metric_upsert - Store or update a business metric definition
llm.question_template_add - Add a question template that can be answered using this data
llm.note_add - Add a general note or insight about the data
llm.search - Search LLM-generated content and insights

Catalog Tools

catalog_upsert - Store data in the catalog
catalog_get - Retrieve from the catalog
catalog_search - Search the catalog
catalog_delete - Delete entry from the catalog
catalog_list - List catalog entries by kind
catalog_merge - Merge multiple catalog entries into a single consolidated entry

Example Usage in Claude Code

Once configured, you can ask Claude:

"List all tables in the testdb schema" "Describe the customers table" "Show me 5 rows from the orders table" "Run SELECT COUNT(*) FROM customers"

Logging

For debugging, the bridge writes logs to /tmp/proxysql_mcp_bridge.log:

tail -f /tmp/proxysql_mcp_bridge.log

The log shows:

stdout writes (byte counts and previews)
tool calls (name, arguments, responses from ProxySQL)
Any errors or issues

This can help diagnose communication issues between Claude Code, the bridge, and ProxySQL.

Troubleshooting

Debug Mode

If tools aren't working, check the bridge log file for detailed information:

cat /tmp/proxysql_mcp_bridge.log

Look for:

"tools/call: name=..." - confirms tool calls are being forwarded
"response from ProxySQL:" - shows what ProxySQL returned
"WRITE stdout:" - confirms responses are being sent to Claude Code

Connection Refused

Make sure ProxySQL MCP server is running:

curl -k https://127.0.0.1:6071/mcp/query \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "ping", "id": 1}'

SSL Certificate Errors

Set PROXYSQL_MCP_INSECURE_SSL=1 to bypass certificate verification.

Authentication Errors

Check that PROXYSQL_MCP_TOKEN matches the token configured in ProxySQL:

SHOW VARIABLES LIKE 'mcp-query_endpoint_auth';

Requirements

Python 3.7+
httpx (pip install httpx)
ProxySQL with MCP enabled

Version

Last Updated: 2026-01-19
MCP Protocol: JSON-RPC 2.0 over HTTPS

6.0 KiB Raw Blame History