Value Proposition Scale your AI integrations confidently with our enterprise-grade HTTP transport. Engineered for cloud-native and remote deployments, it features OAuth 2.0 / OIDC security, robust connection pooling, and multi-agent concurrency to manage intensive workloads.

Use HTTP Transport to unlock enterprise-scale capabilities when:

• Deploying globally to remote or cloud environments
• Facilitating concurrent multi-agent access to a centralized server instance
• Enforcing strict enterprise security via native OAuth 2.0 / OIDC
• Running the server as a standalone network service
• Serverless/stateless deployments (--stateless)
• Horizontally scalable, stateless execution

Use stdio Transport (default) when:

• Running locally with Claude Desktop or Cursor IDE
• Single-user development environment
• Simplest setup with no network configuration needed

# Local installation
npx -y @neverinfamous/mysql-mcp --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /data --mysql mysql://user:password@localhost:3306/database

# Run with port mapping (include Redis and rate limiting env vars for production/enterprise)
docker run -p 3000:3000 \
  -e MYSQL_HOST=host.docker.internal \
  -e MYSQL_USER=user \
  -e MYSQL_PASSWORD=password \
  -e MYSQL_DATABASE=database \
  -e REDIS_URL=redis://host.docker.internal:6379 \
  -e MCP_RATE_LIMIT_MAX=100 \
  -e CODEMODE_RATE_LIMIT_MAX=60 \
  writenotenow/mysql-mcp:latest \
  --transport http \
  --server-host 0.0.0.0 \
  --port 3000 \
  --allowed-io-roots /data

npx -y @neverinfamous/mysql-mcp --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /data --auth-token my-secret --mysql mysql://user:password@localhost:3306/database

npx -y @neverinfamous/mysql-mcp --transport http --server-host 0.0.0.0 --port 3000 --stateless --allowed-io-roots /data --mysql mysql://user:password@localhost:3306/database

The unified HTTP transport layer concurrently serves both modern and legacy protocol endpoints on the same port. This allows both modern and legacy clients to connect simultaneously without requiring separate deployments.

• /mcp (Streamable HTTP): The modern protocol uses a single, session-based endpoint for all communication.
• /sse (Legacy SSE): The backward-compatible protocol establishes a long-lived Server-Sent Events connection.

The modern protocol uses a single, session-based endpoint:

In stateless mode (--stateless), all continuous streaming endpoints (e.g. /sse, GET /mcp) are explicitly disabled to guarantee strict stateless execution via POST /mcp. GET /mcp returns 405 (Method Not Allowed). DELETE /mcp returns 204. /sse and /messages return 404. Each POST /mcp creates a fresh transport. It relies solely on synchronous request-response cycles.

The Mcp-Session-Id header manages sessions. The server returns a session ID during initialize. Clients must include it in subsequent requests. (Note: Strict MCP clients might structurally require the Mcp-Session-Id header. The --stateless mode ignores it internally.)

Example — Initialize a session:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"<protocol-version>","capabilities":{},"clientInfo":{"name":"my-client","version":"<client-version>"}}}'

Example — List tools (with session):

curl -X POST http://localhost:3000/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":{}}'

The legacy protocol supports older MCP clients:

Example:

# Establish SSE connection (will stream events)
curl -N http://localhost:3000/sse
# Send a message (in another terminal, using the sessionId from the SSE stream)
curl -X POST "http://localhost:3000/messages?sessionId=<id>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"<protocol-version>","capabilities":{},"clientInfo":{"name":"my-client","version":"<client-version>"}}}'

All HTTP responses include the following headers:

The HTTP server applies three timeout layers to prevent slow-connection DoS attacks:

The HTTP transport enforces strict session lifecycle management to prevent memory leaks:

• Idle TTL: Configurable via environment variables with sensible defaults. The server terminates idle sessions.
• Absolute TTL: Configurable via environment variables with sensible defaults. Hard limit for any session duration.
• Reaper Interval: Configurable via environment variables with sensible defaults. A background sweep cleans up orphaned sessions. In-flight requests protect active sessions from early termination.

We hardcode CORS to allow all origins (*). This permissiveness defaults to internal routing for seamless orchestrator integration. Secure CORS at the reverse proxy in production. We do not yet support restricting origins via CLI flags.

Enable trustProxy behind reverse proxies. This reads the client IP from X-Forwarded-For. Rate limiting and logging use the real IP.

Default per-IP request throttling prevents abuse. The Transport Rate limiter uses a sliding window with deterministic cleanup. Redis distributes rate limiting across deployments via REDIS_URL. An in-memory fallback exists for all rate limits.

• /health bypass — The server processes health checks before rate limiting. This ensures monitoring probes always succeed.
• Retry-After header — Rate-limited responses include a Retry-After header. It indicates the seconds remaining until the window resets.
• Environment override — Set MCP_RATE_LIMIT_MAX to customize the HTTP request limit. Set CODEMODE_RATE_LIMIT_MAX to customize the Code Mode execution limit.

Two layers enforce request body size:

1. Content-Length header check — fast rejection for well-behaved clients
2. Streaming byte tracking — catches missing headers and chunked encoding

For production deployments, use a structured .env file following fleet groupings:

# Server
MYSQLMCP_PORT=3000
MCP_HOST=0.0.0.0
TRUST_PROXY=false
REDIS_URL=redis://localhost:6379
MCP_RATE_LIMIT_MAX=100
CODEMODE_RATE_LIMIT_MAX=60
# Database
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=app_user
MYSQL_PASSWORD=secure_password
MYSQL_DATABASE=production

HTTP Transport supports OAuth 2.0 / OIDC authentication for enterprise deployments:

npx -y @neverinfamous/mysql-mcp \
  --transport http \
  --port 3000 \
  --allowed-io-roots /data \
  --mysql mysql://user:password@localhost:3306/database \
  --oauth-enabled \
  --oauth-issuer http://localhost:8080/realms/mysql-mcp \
  --oauth-audience mysql-mcp-client

Test your HTTP server with MCP Inspector:

# Start the server
npx -y @neverinfamous/mysql-mcp --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /data --mysql mysql://...
# In another terminal, connect Inspector
npx -y @modelcontextprotocol/inspector http://localhost:3000/sse

curl http://localhost:3000/health
# {"status":"healthy","timestamp":"<ISO-8601-Timestamp>"}

# Run container with port mapping
docker run -d \
  --name mysql-mcp-server \
  -p 3000:3000 \
  -e MYSQL_HOST=host.docker.internal \
  -e MYSQL_USER=user \
  -e MYSQL_PASSWORD=password \
  -e MYSQL_DATABASE=database \
  -e REDIS_URL=redis://host.docker.internal:6379 \
  -e MCP_RATE_LIMIT_MAX=100 \
  -e CODEMODE_RATE_LIMIT_MAX=60 \
  -v mcp-data:/data \
  writenotenow/mysql-mcp:latest \
  --transport http \
  --server-host 0.0.0.0 \
  --port 3000 \
  --allowed-io-roots /data

The following is a minimal excerpt for deploying the HTTP transport via docker-compose.yml. See the Observability & Telemetry page for the full Datadog test ecosystem. It is located in test-server/infrastructure.

# Note: Always include a healthcheck when deploying HTTP transport
services:
  mysql-mcp:
    image: writenotenow/mysql-mcp:latest
    ports:
      - "3000:3000"
    command:
      - --transport
      - http
      - --server-host
      - "0.0.0.0"
      - --port
      - "3000"
      - --allowed-io-roots
      - /data
      - --mysql
      - mysql://user:password@mysql:3306/database
    environment:
      - MYSQL_POOL_SIZE=20
      - REDIS_URL=redis://redis:6379
      - MCP_RATE_LIMIT_MAX=100
      - CODEMODE_RATE_LIMIT_MAX=60
    depends_on:
      - mysql
      - redis
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    volumes:
      - mcp-data:/data
  mysql:
    image: mysql:lts
    environment:
      MYSQL_ROOT_PASSWORD: password
      MYSQL_DATABASE: database
    volumes:
      - mysql-data:/var/lib/mysql
  redis:
    image: redis:alpine
    ports:
      - "6379:6379"
volumes:
  mysql-data:
  mcp-data:

1. Push Docker image to ECR
2. Create ECS task definition with port 3000 exposed
3. Configure ALB to route traffic to the container
4. Set environment variables for MySQL connection

# Build and push to GCR
gcloud builds submit --tag gcr.io/PROJECT_ID/mysql-mcp

# Deploy to Cloud Run
gcloud run deploy mysql-mcp \
  --image gcr.io/PROJECT_ID/mysql-mcp \
  --port 3000 \
  --set-env-vars MYSQL_HOST=...,MYSQL_USER=...,MYSQL_PASSWORD=... \
  --args="--transport","http","--server-host","0.0.0.0","--port","3000","--allowed-io-roots","/data","--stateless"

az container create \
  --resource-group myResourceGroup \
  --name mysql-mcp \
  --image writenotenow/mysql-mcp:latest \
  --ports 3000 \
  --environment-variables \
    MYSQL_HOST=... \
    MYSQL_USER=... \
    MYSQL_PASSWORD=... \
  --command-line "node dist/cli.js --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /data --stateless"

Problem: Client cannot connect to the server

Solutions:

• Verify server is running: curl http://localhost:3000/health
• Check firewall rules allow port 3000
• Ensure --server-host 0.0.0.0 if connecting from another machine
• Check Docker port mapping: -p 3000:3000

Problem: POST /mcp returns 406

Solution: Include the required Accept header:

Accept: application/json, text/event-stream

The server requires clients to accept JSON and SSE formats.

Problem: Requests return 400 Bad Request or 404 Not Found with session errors

Solutions:

• Send the Mcp-Session-Id header from the initialize response
• Cross-protocol guard prevents mixing SSE sessions and /mcp
• Sessions expire when clients disconnect

Problem: Requests return 401 Unauthorized

Solutions:

• Verify OAuth issuer URL is correct
• Check token audience matches --oauth-audience
• Ensure JWKS URI is accessible from the server
• See OAuth troubleshooting section

• Configuration - General configuration options
• OAuth - OAuth 2.0 / OIDC authentication setup
• MCP Inspector - Testing with MCP Inspector
• MCP Protocol Specification - Official MCP docs