HTTP Server Mode

The WhoisXML API MCP Server supports HTTP server mode using modern Streamable HTTP transport for web-based integrations and scenarios where multiple clients need to share a single server instance.

{
  "mcpServers": {
    "whoisxmlapi": {
      "url": "https://mcp-hosted.whoisxmlapi.com/mcp",
      "headers": {
        "Authorization": "Bearer at_..."
      }
    }
  }
}

What is HTTP Server Mode?

HTTP server mode runs the MCP server as a stateless HTTP server that communicates using streamable HTTP transport instead of stdio. This enables:

• Remote AI service access - AI services can connect over HTTP
• Multiple client support - one server instance for multiple AI clients
• Automation tool integration - tools like n8n can connect to remote MCP servers
• HTTP-based communication instead of stdin/stdout

When to Use HTTP Server Mode

Recommended For:

• Remote AI service access - AI services connecting over HTTP
• Automation platforms like n8n (self-hosted or cloud)
• Multiple AI clients sharing one server
• Distributed deployments where stdio isn't feasible
• Multi-tenant hosted services - deploy with per-request authentication

Not Recommended For:

• Single desktop client usage (use stdio mode)
• Direct editor integration (stdio is simpler)
• Simple automation scripts (stdio is more direct)

Basic Usage

Command Line

Start the server in HTTP mode using any installation method:

Using Binary

# Basic HTTP mode (default port 3000)
mcp-whoisxmlapi --http

# Specify custom port
mcp-whoisxmlapi --http --http-port 8080

# With environment variables
export WHOISXMLAPI_TOKEN="your-token"
mcp-whoisxmlapi --http --http-port 3000

Using npm

# Basic HTTP mode
export WHOISXMLAPI_TOKEN="your-token"
npx @whoisxmlapidotcom/mcp-whoisxmlapi --http

# Custom port
npx @whoisxmlapidotcom/mcp-whoisxmlapi --http --http-port 8080

Using Docker

# Basic HTTP mode
docker run --rm -p 3000:3000 \
  -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 \
  --http --http-port 3000

# Custom port
docker run --rm -p 8080:8080 \
  -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 \
  --http --http-port 8080

Debugging HTTP Mode

Monitor your HTTP server and troubleshoot issues:

# Find your HTTP container
docker ps --filter "ancestor=whoisxmlapidotcom/mcp-whoisxmlapi"

# Check if HTTP endpoint is responding
curl -i http://localhost:3000/mcp

# Test the endpoint with a simple MCP request
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

# Check container logs for HTTP-specific output
docker logs -f <container-id> | grep -i http

# Test port accessibility
netstat -tlnp | grep :3000

API Endpoints

The HTTP server exposes a single main endpoint that handles all MCP communication:

/mcp - MCP Protocol Endpoint

POST /mcp

This endpoint handles all MCP protocol communication using streamable HTTP transport. It automatically negotiates the best transport method (direct HTTP responses or streaming) based on the request type and client capabilities.

Request Headers:

Content-Type: application/json

Request Body:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/list",
  "params": {}
}

Response: HTTP response containing MCP protocol message, potentially using streaming for server-initiated notifications.

Integration with Automation Tools

n8n Integration Example:

When configuring n8n (self-hosted or cloud) to connect to your MCP server:

1. Server URL: http://your-server:3000/mcp
2. HTTP Method: POST
3. Content-Type: application/json

Protocol Details

The HTTP server mode uses streamable HTTP transport which:

• Automatically handles protocol negotiation between direct HTTP and streaming modes
• Supports server-initiated notifications when needed
• Operates in stateless mode - each request is completely independent
• Provides better error handling than traditional SSE implementations
• Follows MCP specification for HTTP transport
• Fast shutdown - no session state to clean up

Streamable HTTP Transport

The server uses modern Streamable HTTP transport which provides:

• Automatic protocol negotiation between direct HTTP and streaming modes
• Server-initiated notifications when needed
• Stateless operation - each request is completely independent
• Better error handling than traditional implementations
• Standards compliance with the MCP specification
• Fast shutdown - no session state to clean up

This modern approach replaces older SSE-based implementations while maintaining full compatibility with MCP clients.

TLS/SSL Configuration

The MCP server runs HTTP only and does not provide built-in TLS/SSL support. For production deployments requiring HTTPS, use a reverse proxy to handle TLS termination.

Recommended Approach: Reverse Proxy

Why use a reverse proxy?

• Security: Professional TLS termination with proper certificate management
• Performance: Optimized SSL/TLS handling and caching
• Flexibility: Easy certificate renewal and security policy updates
• Industry Standard: Common practice for production HTTP services

Popular Reverse Proxy Options

Nginx Configuration Example

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/your/certificate.crt;
    ssl_private_key /path/to/your/private.key;

    # Modern SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Docker with Traefik

version: '3.8'
services:
  mcp-server:
    image: whoisxmlapidotcom/mcp-whoisxmlapi:v1
    command: ["--http", "--http-port", "3000"]
    environment:
      - WHOISXMLAPI_TOKEN=your-token
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.mcp.rule=Host(`your-domain.com`)"
      - "traefik.http.routers.mcp.tls=true"
      - "traefik.http.routers.mcp.tls.certresolver=letsencrypt"
      - "traefik.http.services.mcp.loadbalancer.server.port=3000"

Local Development

For local development and testing, plain HTTP is perfectly acceptable:

# Development - HTTP only
mcp-whoisxmlapi --http --http-port 3000

# Access locally
curl http://localhost:3000/mcp

Security Considerations

For production deployments:

1. Always use HTTPS via reverse proxy
2. Restrict network access - bind to localhost when using reverse proxy
3. Enable rate limiting at the reverse proxy level
4. Monitor access logs for security analysis

Troubleshooting

Common Issues

1. Port already in use: Change the port with --http-port
2. Connection refused: Ensure the server is running and firewall allows the port
3. Authentication errors: Verify your WHOISXMLAPI_TOKEN environment variable is set
4. Timeout issues: Check network connectivity and API quotas

Health Check

Test server health:

# Simple health check
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"ping","params":{}}' \
  | jq .

Expected response:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {}
}