HTTP Transport
🚀 Value PropositionEnterprise-Grade & Zero-Trust Architecture: mysql-mcp delivers unparalleled transport security by running full OAuth 2.1 authentication natively over HTTP, ensuring every tool execution is deeply verified against JSON Web Key Sets (JWKS) before touching your database. Expose mysql-mcp remotely with confidence, knowing you have strict rate limits, robust TLS termination, and granular scope enforcement protecting your data.This page explains how to run mysql-mcp as an HTTP server supporting two MCP transport protocols simultaneously — Streamable HTTP for modern clients and legacy SSE for backward compatibility.
Decide When to Use HTTP ModeUse HTTP mode when:- Deploying the server to a remote location (cloud, Docker container)- Multiple AI clients need to connect to the same database- You need OAuth 2.1 authentication for enterprise security- Running the server as a standalone network service- Serverless/stateless deployments (--stateless)Use stdio mode (default) when:- Running locally with Claude Desktop or Cursor IDE- Single-user development environment- Simplest setup with no network configuration needed
💡 Tip: Most users should use stdio mode. HTTP mode is for advanced deployments.
Important:
HTTP transport mode requires --allowed-io-roots to be set to explicitly authorize filesystem access boundaries. The server will fail to start without it.
# Build the project firstpnpm run build# Start HTTP server on port 3001npx @neverinfamous/mysql-mcp --transport http --port 3001 --server-host 0.0.0.0 --allowed-io-roots /data --mysql mysql://user:password@localhost:3306/database# Run with port mappingdocker run -p 3001:3001 writenotenow/mysql-mcp:latest \ --transport http \ --port 3001 \ --server-host 0.0.0.0 \ --allowed-io-roots /data \ --mysql mysql://user:password@host.docker.internal:3306/databasenpx
@neverinfamous/mysql-mcp --transport http --port 3001 --allowed-io-roots /data --auth-token my-secret --mysql mysql://user:password@localhost:3306/databasenpx
@neverinfamous/mysql-mcp --transport http --port 3001 --stateless --allowed-io-roots /data --mysql mysql://user:password@localhost:3306/databaseUnderstand Transport ProtocolsThe HTTP transport supports two MCP protocol versions simultaneously, allowing both modern and legacy clients to connect to the same server.
|
| POST | /mcp
| JSON-RPC requests (initialize, tools/list, etc.) |
| GET | /mcp
| SSE stream for server notifications |
| DELETE | /mcp
| Session termination |In stateless mode (--stateless): GET /mcp returns 405, DELETE /mcp returns 204, /sse and /messages return 404. Each POST /mcp creates a fresh transport with no session persistence, relying exclusively on synchronous HTTP request-response cycles.Sessions are managed via the Mcp-Session-Id header. The server returns a session ID in the response to initialize, and clients must include it in subsequent requests.Example — Initialize a session:
curl
-X POST http://localhost:3001/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}'Example — List tools (with session):
curl
-X POST http://localhost:3001/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Mcp-Session-Id: <session-id-from-initialize>" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'Important:
Streamable HTTP requests must include Accept: application/json, text/event-stream — the server may respond with either format.
- |
|
GET|/sse
| Opens SSE stream, returns/messages?sessionId=<id>endpoint | |POST|/messages?sessionId=<id>| Send JSON-RPC messages to the session |Example:
# Establish SSE connection (will stream events)curl -N http://localhost:3001/sse# Send a message (in another terminal, using the sessionId from the SSE stream)curl -X POST "http://localhost:3001/messages?sessionId=<id>" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}'-- |
| X-Content-Type-Options | nosniff |
| X-Frame-Options | DENY |
| Cache-Control | no-store, no-cache, must-revalidate |
| Content-Security-Policy | default-src 'none'; frame-ancestors 'none' |
| Permissions-Policy | camera=(), microphone=(), geolocation=() |
| Referrer-Policy | no-referrer |
| Strict-Transport-Security | Opt-in via enableHSTS (for HTTPS) |### Server Timeouts (Slowloris Protection)The HTTP server applies three timeout layers to prevent slow-connection DoS attacks:
| Timeout | Value
| Purpose |
|
|
| requestTimeout | 120,000 ms | Maximum time for the entire request lifecycle |
| keepAliveTimeout | 65,000 ms | Idle time before closing keep-alive connections |
| headersTimeout | 66,000 ms | Maximum time to receive complete headers |
The HTTP transport enforces strict session lifecycle management to prevent memory leaks from disconnected clients:
- Idle TTL: 30 minutes. If a session receives no requests, it is terminated.
- Absolute TTL: 24 hours. Hard limit for any session duration.
- Reaper Interval: 1 minute. A background sweep cleans up orphaned sessions. Sessions with in-flight requests are protected from early termination.
CORSCORS is currently hardcoded to allow all origins (*) to facilitate easy connections from web-based clients and inspectors. Restricting origins via CLI flags is not yet supported.
Trust ProxyWhen running behind a reverse proxy (nginx, ALB, Cloudflare, etc.), enable trustProxy to read the client IP from X-Forwarded-For instead of the socket address. This ensures rate limiting and logging use the real client IP.
Rate LimitingPer-IP request throttling is enabled by default to prevent abuse. The Transport Rate limiter (100 HTTP requests/min default) uses a sliding window approach with deterministic cleanup. Rate limiting is distributed across deployments via Redis if REDIS_URL is provided, with a graceful in-memory fallback. (Note: This is distinct from the 60 V8 Code Mode executions/min Execution Rate limit).
-
/healthbypass — Health check requests are served before rate limiting is checked, ensuring monitoring probes always succeed regardless of per-IP quotas -
Retry-Afterheader — Rate-limited responses (429 Too Many Requests) include aRetry-Afterheader indicating seconds until the window resets -
Environment override — Set
MCP_RATE_LIMIT_MAXto customize the per-IP request limit (default: 100 requests/minute)
Body Size EnforcementRequest body size is enforced with two layers:1. Content-Length header check — fast rejection for well-behaved clients2. Streaming byte tracking — catches missing/spoofed headers and chunked encodingDefault maximum body size: 1 MB (1,048,576 bytes).
Environment VariablesFor production deployments, use a structured .env file following fleet groupings:
# ServerMCP_TRANSPORT=httpMYSQLMCP_PORT=3001MCP_HOST=0.0.0.0TRUST_PROXY=falseMCP_RATE_LIMIT_MAX=100# DatabaseMYSQL_HOST=localhostMYSQL_PORT=3306MYSQL_USER=app_userMYSQL_PASSWORD=secure_passwordMYSQL_DATABASE=production|
| --transport, -t | MCP_TRANSPORT
| stdio | Transport type (stdio, http, or sse) |
| --port | MYSQLMCP_PORT
| 3001 | HTTP server port |
| --server-host | MCP_HOST
| localhost | Host to bind HTTP transport to |
| --auth-token | MCP_AUTH_TOKEN
| — | Simple bearer token for HTTP auth |
| --stateless | —
| false | Stateless HTTP mode (no sessions, no SSE) |
| --trust-proxy | TRUST_PROXY
| false | Trust X-Forwarded-For for client IP |
| --enable-hsts | MCP_ENABLE_HSTS
| false | Enable HTTP Strict Transport Security |
| --metrics-export | MCP_METRICS_EXPORT
| false | Enable prometheus metrics endpoint /metrics|
| --allowed-io-roots | ALLOWED_IO_ROOTS
| — | Explicitly authorize filesystem boundaries |
| --oauth-enabled, -o | OAUTH_ENABLED
| false | Enable OAuth 2.1 authentication |
| --oauth-issuer | OAUTH_ISSUER
| — | OAuth 2.1 issuer URL |
| --oauth-audience | OAUTH_AUDIENCE
| — | OAuth 2.1 audience |
| --oauth-jwks-uri | OAUTH_JWKS_URI
| — | JWKS URI (auto-discovered) |
| --oauth-clock-tolerance | OAUTH_CLOCK_TOLERANCE
| — | Clock tolerance in seconds |
| --audit-log | —
| — | Enable JSONL forensic logging and tokens |
| --audit-backup | —
| false | Enable audit backups |
| --audit-reads | —
| false | Include read-scope tool calls in audit log |
| --audit-redact | —
| false | Redact sensitive arguments in audit log |
| --audit-log-max-size | —
| — | Max file size before rotation (bytes) |
| --audit-backup-data | —
| false | Include sample data in pre-mutation snaps |
| --audit-backup-max-size | —
| — | Max table size in bytes for data capture |
| |
| 102400 | Max Code Mode result payload in bytes |
Secure Your Access: Using with OAuth 2.1HTTP mode supports OAuth 2.1 authentication for enterprise deployments:
npx
@neverinfamous/mysql-mcp \ --transport http \ --port 3001 \ --allowed-io-roots /data \ --mysql mysql://user:password@localhost:3306/database \ --oauth-enabled \ --oauth-issuer https://your-keycloak.com/realms/mysql-mcp \ --oauth-audience mysql-mcpSee the OAuth page for complete setup instructions.
# Start the servernpx @neverinfamous/mysql-mcp --transport http --port 3001 --allowed-io-roots /data --mysql mysql://...# In another terminal, connect Inspectornpx @modelcontextprotocol/inspector http://localhost:3001/ssecurl
http://localhost:3001/health# {"status":"healthy","timestamp":"2026-03-05T..."}# Build imagedocker build -t mysql-mcp .# Run container with port mappingdocker run -d \ --name mysql-mcp-server \ -p 3001:3001 \ mysql-mcp \ --transport http \ --port 3001 \ --server-host 0.0.0.0 \ --allowed-io-roots /data \ --mysql mysql://user:password@host.docker.internal:3306/databaseservices
: mysql-mcp: image: writenotenow/mysql-mcp:latest ports: - "3001:3001" command: - --transport - http - --port - "3001" - --allowed-io-roots - /data - --mysql - mysql://user:password@mysql:3306/database environment: - MYSQL_POOL_SIZE=20 depends_on: - mysql mysql: image: mysql:8 environment: MYSQL_ROOT_PASSWORD: password MYSQL_DATABASE: database volumes: - mysql-data:/var/lib/mysqlvolumes: mysql-data:AWS ECS / Fargate1. Push Docker image to ECR2. Create ECS task definition with port 3001 exposed3. Configure ALB to route traffic to the container4. Set environment variables for MySQL connection
# Build and push to GCRgcloud builds submit --tag gcr.io/PROJECT_ID/mysql-mcp# Deploy to Cloud Rungcloud run deploy mysql-mcp \ --image gcr.io/PROJECT_ID/mysql-mcp \ --port 3001 \ --set-env-vars MYSQL_HOST=...,MYSQL_USER=...,MYSQL_PASSWORD=... \ --command "--transport,http,--port,3001,--allowed-io-roots,/data"az
container create \ --resource-group myResourceGroup \ --name mysql-mcp \ --image writenotenow/mysql-mcp:latest \ --ports 3001 \ --environment-variables \ MYSQL_HOST=... \ MYSQL_USER=... \ MYSQL_PASSWORD=... \ --command-line "--transport http --port 3001 --allowed-io-roots /data"Problem: Client cannot connect to the server
Solutions:- Verify server is running: curl http://localhost:3001/health- Check firewall rules allow port 3001- Ensure --server-host 0.0.0.0 if connecting from another machine- Check Docker port mapping: -p 3001:3001
Problem: POST /mcp returns 406
Solution: Include the required Accept header:
Accept: application/json, text/event-stream
The StreamableHTTPServerTransport requires clients to accept both JSON and SSE response formats.
Problem: Requests return 400 Bad Request or 404 Not Found with session-related errors
Solutions:- Ensure you're sending the Mcp-Session-Id header from the initialize response- SSE sessions cannot be used on /mcp and vice versa (cross-protocol guard)- Sessions expire when the client disconnects
Problem: Requests return 401 Unauthorized