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 a MySQL Tool Handler for database exploration.

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;
  

MySQL Tool Handler Configuration

The MySQL Tool Handler provides LLM-based tools for MySQL database exploration, 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

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

mcp-catalog_path

• Type: String (file path)
• Default: "mcp_catalog.db"
• Description: Path to the SQLite catalog database (relative to ProxySQL datadir)
• Runtime: Yes
• Example:

  SET mcp-catalog_path='/path/to/mcp_catalog.db';
  LOAD MCP VARIABLES TO RUNTIME;
  

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

Related Documentation

• MCP Module README - Module overview and setup
• MCP Endpoints - API endpoint documentation
• MySQL Tool Handler - Tool-specific documentation