xhs-mcp

HTTP Transports Support

XHS MCP Server now supports both SSE (Server-Sent Events) and Streamable HTTP transports, in addition to the traditional stdio transport.

Transport Options

1. Streamable HTTP (Recommended)

• Protocol Version: 2025-03-26
• Endpoint: /mcp
• Methods: GET, POST, DELETE
• Features:
  • Unified endpoint for all operations
  • Session management with resumability
  • On-demand streaming
  • Stateless server support

2. HTTP + SSE (Legacy)

• Protocol Version: 2024-11-05
• Endpoints:
  • /sse (GET) - Establish SSE stream
  • /messages (POST) - Send messages
• Features:
  • Traditional SSE implementation
  • Backward compatibility

3. Stdio (Default)

• Protocol: Standard MCP stdio transport
• Usage: Direct process communication
• Features:
  • Zero configuration
  • Process-based communication

Usage

Starting the HTTP Server

# Start HTTP server on default port 3000
npm run start:http

# Start HTTP server on custom port
npm run start:http -- --port 8080

# Development mode with HTTP server
npm run dev:http

# Development mode with custom port
npm run dev:http -- --port 8080

Command Line Options

# Show help
node dist/index.js --help

# Start in stdio mode (default)
node dist/index.js --mode stdio

# Start in HTTP mode
node dist/index.js --mode http --port 3000

API Endpoints

Health Check

GET /health

Returns server status and supported transports.

Response:

{
  "status": "healthy",
  "server": "xhs-mcp",
  "version": "0.2.10",
  "transports": ["streamable-http", "sse"]
}

Streamable HTTP Transport

Initialize Session

POST /mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": {
      "name": "client-name",
      "version": "1.0.0"
    }
  }
}

Response Headers:

Mcp-Session-Id: <session-id>

Send Requests

POST /mcp
Content-Type: application/json
Mcp-Session-Id: <session-id>

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

Establish SSE Stream

GET /mcp
Mcp-Session-Id: <session-id>

Terminate Session

DELETE /mcp
Mcp-Session-Id: <session-id>

SSE Transport (Legacy)

Establish SSE Stream

GET /sse

Send Messages

POST /messages?sessionId=<session-id>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "client-name",
      "version": "1.0.0"
    }
  }
}

Testing

A test script is provided to verify the HTTP server functionality:

# Start the HTTP server in one terminal
npm run dev:http

# Run tests in another terminal
node test-http-server.js

Configuration

Environment Variables

• XHS_ENABLE_LOGGING=true - Enable detailed logging
• PORT - HTTP server port (default: 3000)

CORS Configuration

The HTTP server is configured with permissive CORS settings for development:

app.use(cors({
  origin: '*', // Allow all origins
  exposedHeaders: ['Mcp-Session-Id']
}));

For production, you should restrict the origin to specific domains.

Security Considerations

DNS Rebinding Protection

Both SSE and Streamable HTTP transports support DNS rebinding protection:

const transport = new SSEServerTransport('/messages', res, {
  allowedHosts: ['localhost', '127.0.0.1'],
  allowedOrigins: ['http://localhost:3000'],
  enableDnsRebindingProtection: true
});

Session Management

• Session IDs are generated using cryptographically secure UUIDs
• Sessions are automatically cleaned up when connections close
• Invalid session IDs are rejected with appropriate error responses

Migration Guide

From Stdio to HTTP

1. Update client configuration to use HTTP endpoints instead of stdio
2. Handle session management for stateful operations
3. Implement proper error handling for HTTP-specific errors
4. Consider CORS requirements for browser-based clients

From SSE to Streamable HTTP

1. Update protocol version from 2024-11-05 to 2025-03-26
2. Use unified /mcp endpoint instead of separate /sse and /messages
3. Implement session ID handling in request headers
4. Update client to handle both streaming and direct responses

Troubleshooting

Common Issues

1. Port already in use: Change the port using --port option
2. CORS errors: Configure allowed origins in production
3. Session not found: Ensure session ID is properly included in headers
4. Connection timeouts: Check network configuration and firewall

Debug Mode

Enable detailed logging:

XHS_ENABLE_LOGGING=true npm run dev:http

Health Check

Always verify server status:

curl http://localhost:3000/health

This site is open source. Improve this page.