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:**
  ```sql
  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:**
  ```sql
  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:**
  ```sql
  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:**
  ```sql
  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:**
  ```sql
  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:**
  ```sql
  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:**
  ```sql
  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:**
  ```sql
  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:**
  ```sql
  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:**
  ```sql
  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:**
  ```sql
  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:**
  ```sql
  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:**
  ```sql
  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:**
  ```sql
  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

```sql
-- 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

```sql
-- 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

```sql
-- 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:

```sql
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](Architecture.md) - Module architecture and endpoint specifications
- [Tool Discovery Guide](Tool_Discovery_Guide.md) - Tool discovery and usage documentation