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

1. Install dependencies:

pip install httpx

2. Make the script executable:

chmod +x proxysql_mcp_stdio_bridge.py

Configuration

Environment Variables

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

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), requires target_id
• agent.run_start - Start a new agent run for discovery coordination, requires target_id + run_id
• 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 (target_id + run_id)
• 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

Note: catalog/agent/llm tools are target-scoped. Always include target_id when a tool accepts run_id.

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