HTTP Transport

HTTP/SSE Transport

This page explains how to run mysql-mcp as an HTTP server using Server-Sent Events (SSE) for MCP protocol communication.

---

When to Use HTTP Mode

Use 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 service accessible over a network

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.

---

Quick Start

Local Installation

# Build the project first
npm run build

# Start HTTP server on port 3000
node dist/cli.js --transport http --port 3000 --mysql mysql://user:password@localhost:3306/database

Docker

# Run with port mapping
docker run -p 3000:3000 writenotenow/mysql-mcp \
  --transport http \
  --port 3000 \
  --mysql mysql://user:password@host.docker.internal:3306/database

---

Available Endpoints

Endpoint	Method	Purpose
/sse	GET	Establish MCP connection via Server-Sent Events
/messages	POST	Send JSON-RPC messages to the server
/health	GET	Health check endpoint (returns {"status":"healthy"})
/.well-known/oauth-protected-resource	GET	OAuth 2.1 metadata (when OAuth is enabled)

---

Configuration Options

CLI Arguments

Argument	Environment Variable	Default	Description
--transport	-	stdio	Transport type (stdio, http, or sse)
--port	PORT	3000	HTTP server port
--host	HOST	localhost	HTTP server host
--cors-origins	CORS_ORIGINS	-	Comma-separated allowed origins

Example with CORS

node dist/cli.js \
  --transport http \
  --port 3000 \
  --host 0.0.0.0 \
  --cors-origins "https://example.com,https://app.example.com" \
  --mysql mysql://user:password@localhost:3306/database

---

Using with OAuth 2.1

HTTP mode supports OAuth 2.1 authentication for enterprise deployments:

node dist/cli.js \
  --transport http \
  --port 3000 \
  --mysql mysql://user:password@localhost:3306/database \
  --oauth-enabled \
  --oauth-issuer https://your-keycloak.com/realms/mysql-mcp \
  --oauth-audience mysql-mcp

See the OAuth page for complete setup instructions.

---

Connecting MCP Clients

Using MCP Inspector

Test your HTTP server with MCP Inspector:

# Start the server
node dist/cli.js --transport http --port 3000 --mysql mysql://...

# In another terminal, connect Inspector
npx @modelcontextprotocol/inspector http://localhost:3000/sse

Custom Client Implementation

To connect a custom MCP client to your HTTP server:

1. Establish SSE connection: Send a GET request to /sse
2. Receive messages: Listen for Server-Sent Events on the connection
3. Send messages: POST JSON-RPC messages to /messages

Example using curl:

# Health check
curl http://localhost:3000/health

# Establish SSE connection (will stream events)
curl -N http://localhost:3000/sse

# Send a message (in another terminal)
curl -X POST http://localhost:3000/messages \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

---

Docker Deployment

Basic Deployment

# Build image
docker build -t mysql-mcp .

# Run container with port mapping
docker run -d \
  --name mysql-mcp-server \
  -p 3000:3000 \
  mysql-mcp \
  --transport http \
  --port 3000 \
  --mysql mysql://user:password@host.docker.internal:3306/database

Docker Compose

version: '3.8'

services:
  mysql-mcp:
    image: writenotenow/mysql-mcp:latest
    ports:
      - "3000:3000"
    command:
      - --transport
      - http
      - --port
      - "3000"
      - --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/mysql

volumes:
  mysql-data:

---

Cloud Deployment

AWS ECS / Fargate

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

Google Cloud Run

# 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=... \
  --command "--transport,http,--port,3000"

Azure Container Instances

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 "--transport http --port 3000"

---

Troubleshooting

Connection Refused

Problem: Client cannot connect to /sse endpoint

Solutions:

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

CORS Errors

Problem: Browser-based clients show CORS errors

Solution: Add allowed origins:

--cors-origins "https://your-client-domain.com"

OAuth Authentication Failures

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

---

See Also

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