proxysql/doc/MCP/VARIABLES.md

MCP Variables

This document describes all configuration variables for the MCP (Model Context Protocol) module in ProxySQL.

Overview

The MCP module provides JSON-RPC 2.0 over HTTPS for LLM integration with ProxySQL. It includes endpoints for configuration, observation, querying, administration, caching, and AI features, each with dedicated tool handlers for database exploration and LLM integration.

All variables are stored in the global_variables table with the mcp- prefix and can be modified at runtime through the admin interface.

Variable Reference

Server Configuration

mcp-enabled

• Type: Boolean
• Default: false
• Description: Enable or disable the MCP HTTPS server
• Runtime: Yes (requires restart of MCP server to take effect)
• Example:

  SET mcp-enabled=true;
  LOAD MCP VARIABLES TO RUNTIME;
  

mcp-port

• Type: Integer
• Default: 6071
• Description: HTTPS port for the MCP server
• Range: 1024-65535
• Runtime: Yes (requires restart of MCP server to take effect)
• Example:

  SET mcp-port=7071;
  LOAD MCP VARIABLES TO RUNTIME;
  

mcp-timeout_ms

• Type: Integer
• Default: 30000 (30 seconds)
• Description: Request timeout in milliseconds for all MCP endpoints
• Range: 1000-300000 (1 second to 5 minutes)
• Runtime: Yes
• Example:

  SET mcp-timeout_ms=60000;
  LOAD MCP VARIABLES TO RUNTIME;
  

Endpoint Authentication

The following variables control authentication (Bearer tokens) for specific MCP endpoints. If left empty, no authentication is required for that endpoint.

mcp-config_endpoint_auth

• Type: String
• Default: "" (empty)
• Description: Bearer token for /mcp/config endpoint
• Runtime: Yes
• Example:

  SET mcp-config_endpoint_auth='my-secret-token';
  LOAD MCP VARIABLES TO RUNTIME;
  

mcp-observe_endpoint_auth

• Type: String
• Default: "" (empty)
• Description: Bearer token for /mcp/observe endpoint
• Runtime: Yes
• Example:

  SET mcp-observe_endpoint_auth='observe-token';
  LOAD MCP VARIABLES TO RUNTIME;
  

mcp-query_endpoint_auth

• Type: String
• Default: "" (empty)
• Description: Bearer token for /mcp/query endpoint
• Runtime: Yes
• Example:

  SET mcp-query_endpoint_auth='query-token';
  LOAD MCP VARIABLES TO RUNTIME;
  

mcp-admin_endpoint_auth

• Type: String
• Default: "" (empty)
• Description: Bearer token for /mcp/admin endpoint
• Runtime: Yes
• Example:

  SET mcp-admin_endpoint_auth='admin-token';
  LOAD MCP VARIABLES TO RUNTIME;
  

mcp-cache_endpoint_auth

• Type: String
• Default: "" (empty)
• Description: Bearer token for /mcp/cache endpoint
• Runtime: Yes
• Example:

  SET mcp-cache_endpoint_auth='cache-token';
  LOAD MCP VARIABLES TO RUNTIME;
  

mcp-ai_endpoint_auth

• Type: String
• Default: "" (empty)
• Description: Bearer token for /mcp/ai endpoint
• Runtime: Yes
• Example:

  SET mcp-ai_endpoint_auth='ai-token';
  LOAD MCP VARIABLES TO RUNTIME;
  

Query Tool Handler Configuration

The Query Tool Handler provides LLM-based tools for MySQL database exploration and two-phase discovery, including:

• inventory - List databases and tables
• structure - Get table schema
• profiling - Analyze query performance
• sampling - Sample table data
• query - Execute SQL queries
• relationships - Infer table relationships
• catalog - Catalog operations
• discovery - Two-phase discovery tools (static harvest + LLM analysis)
• agent - Agent coordination tools
• llm - LLM interaction tools

mcp-mysql_hosts

• Type: String (comma-separated)
• Default: "127.0.0.1"
• Description: Comma-separated list of MySQL host addresses
• Runtime: Yes
• Example:

  SET mcp-mysql_hosts='192.168.1.10,192.168.1.11,192.168.1.12';
  LOAD MCP VARIABLES TO RUNTIME;
  

mcp-mysql_ports

• Type: String (comma-separated)
• Default: "3306"
• Description: Comma-separated list of MySQL ports (corresponds to mcp-mysql_hosts)
• Runtime: Yes
• Example:

  SET mcp-mysql_ports='3306,3307,3308';
  LOAD MCP VARIABLES TO RUNTIME;
  

mcp-mysql_user

• Type: String
• Default: "" (empty)
• Description: MySQL username for tool handler connections
• Runtime: Yes
• Example:

  SET mcp-mysql_user='mcp_user';
  LOAD MCP VARIABLES TO RUNTIME;
  

mcp-mysql_password

• Type: String
• Default: "" (empty)
• Description: MySQL password for tool handler connections
• Runtime: Yes
• Note: Password is stored in plaintext in global_variables. Use restrictive MySQL user permissions.
• Example:

  SET mcp-mysql_password='secure-password';
  LOAD MCP VARIABLES TO RUNTIME;
  

mcp-mysql_schema

• Type: String
• Default: "" (empty)
• Description: Default database/schema to use for tool operations
• Runtime: Yes
• Example:

  SET mcp-mysql_schema='mydb';
  LOAD MCP VARIABLES TO RUNTIME;
  

Catalog Configuration

The catalog database path is hardcoded to mcp_catalog.db in the ProxySQL datadir and cannot be changed at runtime. The catalog stores:

• Database schemas discovered during two-phase discovery
• LLM memories (summaries, domains, metrics)
• Tool usage statistics
• Search history

Management Commands

View Variables

-- View all MCP variables
SHOW MCP VARIABLES;

-- View specific variable
SELECT variable_name, variable_value
FROM global_variables
WHERE variable_name LIKE 'mcp-%';

Modify Variables

-- Set a variable
SET mcp-enabled=true;

-- Load to runtime
LOAD MCP VARIABLES TO RUNTIME;

-- Save to disk
SAVE MCP VARIABLES TO DISK;

Checksum Commands

-- Checksum of disk variables
CHECKSUM DISK MCP VARIABLES;

-- Checksum of memory variables
CHECKSUM MEM MCP VARIABLES;

-- Checksum of runtime variables
CHECKSUM MEMORY MCP VARIABLES;

Variable Persistence

Variables can be persisted across three layers:

1. Disk (disk.global_variables) - Persistent storage
2. Memory (main.global_variables) - Active configuration
3. Runtime (runtime_global_variables) - Currently active values

LOAD MCP VARIABLES FROM DISK    → Disk to Memory
LOAD MCP VARIABLES TO RUNTIME   → Memory to Runtime
SAVE MCP VARIABLES TO DISK      → Memory to Disk
SAVE MCP VARIABLES FROM RUNTIME → Runtime to Memory

Status Variables

The following read-only status variables are available:

Variable	Description
mcp_total_requests	Total number of MCP requests received
mcp_failed_requests	Total number of failed MCP requests
mcp_active_connections	Current number of active MCP connections

To view status variables:

SELECT * FROM stats_mysql_global WHERE variable_name LIKE 'mcp_%';

Security Considerations

1. Authentication: Always set authentication tokens for production environments
2. HTTPS: The MCP server uses HTTPS with SSL certificates from the ProxySQL datadir
3. MySQL Permissions: Create a dedicated MySQL user with limited permissions for the tool handler:
   • SELECT permissions for inventory/structure tools
   • PROCESS permission for profiling
   • Limited SELECT on specific tables for sampling/query tools
4. Network Access: Consider firewall rules to restrict access to mcp-port

Version

• MCP Thread Version: 0.1.0
• Protocol: JSON-RPC 2.0 over HTTPS
• Last Updated: 2026-01-19

Related Documentation

• MCP Architecture - Module architecture and endpoint specifications
• Tool Discovery Guide - Tool discovery and usage documentation