mcp-echo-streamablehttp-server-stateful

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

# Using pip/pixi installation
mcp-echo-stateful-server

# Or using Python module
python -m mcp_echo_streamablehttp_server_stateful

# With custom configuration
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.