MCP Echo StreamableHTTP Server - Stateful
A stateful diagnostic MCP echo server with session management, message queuing, and 11 comprehensive debug tools for testing OAuth flows and MCP protocol compliance.
Features
Stateful Session Management
- Persistent Sessions: UUID-based session tracking across requests
- Message Queuing: Per-session message buffers for async clients
- Automatic Cleanup: Background task removes expired sessions
- Session Context: Store and retrieve state between requests
MCP Protocol Compliance
- Full MCP 2025-06-18 StreamableHTTP transport implementation
- Supports multiple protocol versions (configurable)
- JSON-RPC 2.0 message handling
- Proper initialize � initialized lifecycle
11 Debug Tools
- echo - Echo messages with session context
- replayLastEcho - Replay the last echoed message (stateful feature!)
- printHeader - Display all HTTP headers categorized
- bearerDecode - Decode JWT tokens without verification
- authContext - Show OAuth authentication context
- requestTiming - Display request performance metrics
- corsAnalysis - Analyze CORS configuration
- environmentDump - Show sanitized environment config
- healthProbe - Deep health check with session stats
- sessionInfo - Display session information and statistics
- whoIStheGOAT - AI-powered excellence analyzer
Endpoints
POST /mcp
- Accepts JSON-RPC 2.0 requests
- Creates/manages sessions via Mcp-Session-Id header
- Supports both JSON and SSE response formats
- Returns session ID for stateful clients
GET /mcp
- Polls for queued messages (requires session ID)
- Returns Server-Sent Events (SSE) stream
- Sends keep-alive pings when queue is empty
Configuration
Environment variables:
MCP_ECHO_HOST
- Host to bind (default: 0.0.0.0)
MCP_ECHO_PORT
- Port to bind (default: 3000)
MCP_ECHO_DEBUG
- Enable debug logging (default: true)
MCP_SESSION_TIMEOUT
- Session timeout in seconds (default: 3600)
MCP_PROTOCOL_VERSION
- Default protocol version (default: 2025-06-18)
MCP_PROTOCOL_VERSIONS_SUPPORTED
- Comma-separated supported versions
Installation
Using pip
pip install mcp-echo-streamablehttp-server-stateful
Using pixi
pixi add --pypi mcp-echo-streamablehttp-server-stateful
Docker Deployment
FROM python:3.11-slim
# Install the package
RUN pip install mcp-echo-streamablehttp-server-stateful
# Set environment variables
ENV MCP_ECHO_HOST=0.0.0.0
ENV MCP_ECHO_PORT=3000
ENV MCP_ECHO_DEBUG=true
# Expose the port
EXPOSE 3000
# Run the server
CMD ["python", "-m", "mcp_echo_streamablehttp_server_stateful"]
The service includes:
- Health check with protocol validation
- Traefik labels for OAuth integration
- Volume mounts for logs
- Automatic HTTPS via Let's Encrypt
Session Features
Message Queuing
- FIFO queue per session (max 100 messages)
- Automatic overflow protection
- Complete queue drain on GET requests
Session Storage
Each session maintains:
- Creation and last activity timestamps
- Protocol version and client info
- Initialization state
- Custom application state (e.g., last echo message)
Background Cleanup
- Runs every 60 seconds
- Removes sessions older than timeout
- Clears associated message queues
Quick Start
Running Locally
mcp-echo-stateful-server
python -m mcp_echo_streamablehttp_server_stateful
MCP_ECHO_PORT=8080 MCP_SESSION_TIMEOUT=7200 mcp-echo-stateful-server
Using with Docker Compose
services:
mcp-echo-stateful:
image: mcp-echo-stateful:latest
build:
context: ./mcp-echo-streamablehttp-server-stateful
environment:
- MCP_ECHO_HOST=0.0.0.0
- MCP_ECHO_PORT=3000
- MCP_ECHO_DEBUG=true
- MCP_SESSION_TIMEOUT=3600
- MCP_PROTOCOL_VERSION=2025-06-18
ports:
- "3000:3000"
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/mcp", "-X", "POST",
"-H", "Content-Type: application/json",
"-d", '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"healthcheck","version":"1.0"}},"id":1}']
interval: 30s
timeout: 5s
retries: 3
Example Usage
Initialize Session
curl -X POST https://echo-stateful.yourdomain.com/mcp \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18","clientInfo":{"name":"test","version":"1.0"}},"id":1}'
Use Stateful Tool
curl -X POST https://echo-stateful.yourdomain.com/mcp \
-H "Content-Type: application/json" \
-H "Mcp-Session-Id: <session-id-from-initialize>" \
-d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"replayLastEcho","arguments":{}},"id":2}'
Differences from Stateless Version
This stateful version adds:
- Session management with UUID tracking
- Message queuing for async delivery
- Stateful tools (replayLastEcho)
- GET endpoint for message polling
- Background cleanup tasks
- Session statistics and monitoring
License
Apache 2.0 - See LICENSE file for details.