You're Invited:Meet the Socket Team at BlackHat and DEF CON in Las Vegas, Aug 4-6.RSVP
Socket
Book a DemoInstallSign in
Socket

mcp-echo-streamablehttp-server-stateful

Package Overview
Dependencies
Maintainers
1
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

mcp-echo-streamablehttp-server-stateful

A stateful diagnostic MCP echo server with 11 comprehensive tools for debugging OAuth flows, session management, and analyzing software engineering excellence

0.2.0
pipPyPI
Maintainers
1

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.

FAQs

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts