MCP Integration

Table of Contents

• Overview
• Native HTTP/HTTPS Integration
  • Configuration
  • Enabling the MCP Server
  • HTTPS Support
  • MCP Endpoints
  • Authentication
  • JSON-RPC 2.0 Protocol
• Claude Code Native HTTP/HTTPS Transport
  • HTTP vs HTTPS with Claude Code
  • Configuration
  • Managing Your MCP Server
  • Available Tools
  • Example Usage
  • Troubleshooting
• STDIO Bridge Integration (for Claude Code)
  • Architecture
  • Installation
  • Configuration
  • Available Tools in Claude Code
  • Example Usage in Claude Code
  • Debugging
• Choosing an Integration Approach
  • Quick Decision Guide
• Related Documentation

Overview

ProxySQL v4.0 implements the Model Context Protocol (MCP) using native HTTP/HTTPS support. This enables AI agents like Claude Code to interact directly with ProxySQL for database discovery, query execution, and configuration management.

There are three approaches for connecting to ProxySQL’s MCP server:

┌─────────────────┐      HTTPS      ┌──────────────────────────────────┐
│  Custom AI App  │ ──────────────> │                                  │
└─────────────────┘                 │           ProxySQL MCP           │
                                   │          (HTTP/HTTPS)             │
┌─────────────────┐      HTTPS     │            Server                │
│  Claude Code    │ ──────────────> │                                  │
│  (native http)  │    or HTTP     └──────────────────────────────────┘
└─────────────────┘
┌─────────────────┐      stdio      ┌──────────────────┐     HTTPS      ┌──────────┐
│  Claude Code    │ ──────────────>  │  STDIO Bridge    │  ──────────>  │ ProxySQL │
│  (stdio bridge) │                 │  (Python Script) │               │  MCP     │
└─────────────────┘                 └──────────────────┘               └──────────┘

Native HTTP/HTTPS Integration

Overview

ProxySQL’s MCP server is built on libhttpserver and supports both HTTP and HTTPS modes. The server exposes multiple endpoints, each with a dedicated handler and required Bearer token authentication.

Configuration

Enabling the MCP Server

-- Enable the MCP server with HTTPS
SET mcp-enabled='true';
SET mcp-use_ssl='true';
SET mcp-port='6071';
LOAD MCP VARIABLES TO RUNTIME;

HTTPS Support

ProxySQL uses the same SSL certificates configured for the admin interface. When mcp-use_ssl is enabled:

• The server only accepts HTTPS connections
• SSL certificates from the admin-certificates configuration are used
• Clients must support HTTPS/TLS handshake

MCP Endpoints

The ProxySQL MCP server implements multiple endpoints, each with its own tool set and authentication:

See MCP Endpoints for complete endpoint documentation.

Authentication

Each endpoint requires its own non-empty Bearer token. An empty endpoint token disables access rather than allowing unauthenticated requests:

-- Set authentication token for the query endpoint
SET mcp-query_endpoint_auth='your_secure_token_here';
LOAD MCP VARIABLES TO RUNTIME;

Clients can authenticate via:

1. Authorization Header:

   Authorization: Bearer your_token_here

2. Query Parameter:

   https://127.0.0.1:6071/mcp/query?token=your_token_here

JSON-RPC 2.0 Protocol

The MCP server implements the JSON-RPC 2.0 protocol. All requests follow this format:

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

Example: List Available Tools

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

Example: Call a Tool

curl -k https://127.0.0.1:6071/mcp/query \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_schemas",
      "arguments": {}
    }
  }'

Python Client Example

import httpx
import json

async def call_proxysql_mcp():
    endpoint = "https://127.0.0.1:6071/mcp/query"
    token = "your_token_here"

    async with httpx.AsyncClient(verify=False) as client:
        # List available tools
        request = {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/list",
            "params": {}
        }

        response = await client.post(
            endpoint,
            json=request,
            headers={"Authorization": f"Bearer {token}"}
        )

        print(response.json())

        # Call a tool
        request = {
            "jsonrpc": "2.0",
            "id": 2,
            "method": "tools/call",
            "params": {
                "name": "list_tables",
                "arguments": {"schema": "testdb"}
            }
        }

        response = await client.post(
            endpoint,
            json=request,
            headers={"Authorization": f"Bearer {token}"}
        )

        print(response.json())

Claude Code Native HTTP/HTTPS Transport

Overview

Claude Code supports native HTTP/HTTPS transport via the --transport http option. This allows direct connection to ProxySQL’s MCP server without requiring a stdio bridge.

HTTP vs HTTPS with Claude Code

Configuration

Option 1: Using HTTP (Recommended for Development)

Disable SSL in ProxySQL and use HTTP:

-- Configure ProxySQL for HTTP
SET mcp-enabled='true';
SET mcp-use_ssl='false';
SET mcp-port='6071';
SET mcp-query_endpoint_auth='your_token_here';
LOAD MCP VARIABLES TO RUNTIME;

Add to Claude Code using the CLI:

# Add ProxySQL as an authenticated HTTP MCP server
claude mcp add --transport http proxysql http://127.0.0.1:6071/mcp/query \
  --header "Authorization: Bearer your_token_here"

Or add to .mcp.json in your project:

{
  "mcpServers": {
    "proxysql": {
      "type": "http",
      "url": "http://127.0.0.1:6071/mcp/query",
      "headers": {
        "Authorization": "Bearer your_token_here"
      }
    }
  }
}

Option 2: Using HTTPS (Requires Valid Certificate)

-- Configure ProxySQL for HTTPS with valid certificate
SET mcp-enabled='true';
SET mcp-use_ssl='true';
SET mcp-port='6071';
SET mcp-query_endpoint_auth='your_token_here';
LOAD MCP VARIABLES TO RUNTIME;

Add to Claude Code:

# Add ProxySQL as an HTTPS MCP server
claude mcp add --transport http proxysql https://127.0.0.1:6071/mcp/query \
  --header "Authorization: Bearer your_token_here"

Or in .mcp.json:

{
  "mcpServers": {
    "proxysql": {
      "type": "http",
      "url": "https://127.0.0.1:6071/mcp/query",
      "headers": {
        "Authorization": "Bearer your_token_here"
      }
    }
  }
}

Managing Your MCP Server

# List all configured servers
claude mcp list

# Get details for the ProxySQL server
claude mcp get proxysql

# Remove the server
claude mcp remove proxysql

# Check server status within Claude Code
/mcp

Available Tools

Once connected via HTTP/HTTPS, the tools advertised by the selected endpoint are available directly in Claude Code. See MCP Endpoints for the released endpoint status and tool references.

Example Usage

# 1. Configure ProxySQL for HTTP
mysql -h 127.0.0.1 -P 6032 -u admin -padmin
> SET mcp-enabled='true';
> SET mcp-use_ssl='false';
> SET mcp-query_endpoint_auth='your_token_here';
> LOAD MCP VARIABLES TO RUNTIME;

# 2. Add to Claude Code
claude mcp add --transport http proxysql http://127.0.0.1:6071/mcp/query \
  --header "Authorization: Bearer your_token_here"

# 3. Use in Claude Code
> "List all tables in the testdb schema"
> "Show me the structure of the customers table"
> "Run SELECT COUNT(*) FROM orders"

Troubleshooting

Connection Refused:

# Verify ProxySQL MCP is running
curl http://127.0.0.1:6071/mcp/query \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token_here" \
  -d '{"jsonrpc": "2.0", "method": "ping", "id": 1}'

SSL Certificate Error:

• Claude Code does not support self-signed certificates
• Either use HTTP (mcp-use_ssl=false) or use the STDIO Bridge

Authentication Error:

# Check configured token in ProxySQL
mysql -h 127.0.0.1 -P 6032 -u admin -padmin
> SHOW VARIABLES LIKE 'mcp-query_endpoint_auth';

STDIO Bridge Integration (for Claude Code)

Overview

The STDIO Bridge is a Python script that translates between stdio-based MCP (used by Claude Code) and ProxySQL’s HTTPS MCP endpoint. This enables Claude Code to connect to ProxySQL using its native stdio transport.

Architecture

┌─────────────┐     stdio      ┌──────────────────┐     HTTPS      ┌──────────┐
│  Claude Code│  ──────────>  │  STDIO Bridge    │  ──────────>  │ ProxySQL │
│  (MCP Client)│               │  (Python Script) │               │  MCP     │
└─────────────┘               └──────────────────┘               └──────────┘

Installation

1. Install dependencies:

pip install httpx

2. Locate the bridge script:

The STDIO bridge is located in the ProxySQL source tree at:

/path/to/proxysql-source/scripts/mcp/proxysql_mcp_stdio_bridge.py

Configuration

Environment Variables

Claude Code Configuration

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

{
  "mcpServers": {
    "proxysql": {
      "command": "python3",
      "args": ["/path/to/proxysql-source/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"
      }
    }
  }
}

Supported MCP Methods

The STDIO bridge supports the standard MCP methods:

Available Tools in Claude Code

The selected endpoint’s released registry determines which tools Claude Code sees. For /mcp/query, use Query Tools for the tool families and MCP Catalog for the exact dotted catalog.* tools. Use tools/list against the running server as the authoritative runtime inventory.

Example Usage in Claude Code

Once configured, you can interact with ProxySQL using natural language:

“List all tables in the testdb schema” “Describe the customers table structure” “Show me 5 rows from the orders table” “Run SELECT COUNT(*) FROM customers GROUP BY country” “Find relationships between the orders and customers tables”

Debugging

The STDIO bridge writes detailed logs to help troubleshoot issues:

# View the bridge log in real-time
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

Troubleshooting Connection Issues

Check if ProxySQL MCP is running:

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

Verify authentication token:

SHOW VARIABLES LIKE 'mcp-query_endpoint_auth';

Check bridge logs:

cat /tmp/proxysql_mcp_bridge.log

Requirements

Choosing an Integration Approach

Quick Decision Guide

Use Native HTTP when:

• Quick local development setup
• Trusted network environment (localhost, private network)
• Don’t want to deal with SSL certificate configuration
• Building prototypes or proof-of-concepts

# Simple authenticated HTTP setup
claude mcp add --transport http proxysql http://127.0.0.1:6071/mcp/query \
  --header "Authorization: Bearer your_token_here"

Use Native HTTPS when:

• Production environment with valid SSL certificates
• Need encrypted communication
• Connecting over untrusted networks
• Using commercially-signed or Let’s Encrypt certificates

# HTTPS with valid certificate
claude mcp add --transport http proxysql https://your-server.com:6071/mcp/query \
  --header "Authorization: Bearer your_token"

Use STDIO Bridge when:

• ProxySQL uses self-signed SSL certificates
• Need to bypass certificate validation in development
• Working in an environment where certificate installation is difficult
• Prefer stdio-based isolation for security

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

Related Documentation

• MCP Server - MCP server overview
• MCP Endpoints - Complete endpoint reference
• MCP Tools (Query) - Database exploration tools
• MCP Tools (RAG) - Retrieval-Augmented Generation tools
• MCP Variables - Configuration variables
• MCP Autodiscovery - Two-phase discovery mechanism
• NL2SQL - Natural language to SQL conversion