Simple Streamable HTTP MCP Server

A clean implementation of an MCP server using the Streamable HTTP transport, following the official MCP patterns.

Features

Streamable HTTP Transport: Supports both JSON responses and Server-Sent Events (SSE)
Session Management: Proper session handling with unique session IDs
Progress Notifications: Long-running tools send progress updates
Multiple Tools:
- hello_world: Simple greeting tool
- get_server_info: Returns server information
- long_running_test: Configurable duration test with progress (default: 30s)
- slow_test: 10-minute test with progress updates

Architecture

This server follows the MCP team's recommended patterns:

Session-based Architecture: Each client gets a unique session ID
Transport Reuse: Transports are stored and reused for subsequent requests
Proper Initialization: New sessions are created only on initialization requests
Clean Shutdown: All transports are properly closed on server shutdown

Running the Server

# Install dependencies npm ci # Run the server (default port: 3001, DEBUG logging enabled by default) npm run start # Run without debug logging, or edit `.env` to set DEBUG=false DEBUG=false npm run start # Run in development mode (auto-reload) npm run dev

Testing

Use the provided test script to verify the server is working correctly:

npm run test:http

This will test:

Session initialization
Tool listing and calling
Session ID management
SSE streaming
Session termination

Progress Notifications

The long_running_test and slow_test tools demonstrate progress notifications:

// Example tool call with progress { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "long_running_test", "arguments": { "duration": 60, "steps": 12, "message": "Testing progress notifications" }, "_meta": { "progressToken": "unique-progress-token" } }, "id": 1 }

The server will send progress notifications:

{ "method": "notifications/progress", "params": { "progress": 1, "total": 12, "progressToken": "unique-progress-token" } }

Key Differences from Basic Examples

Proper Session Management: Sessions are created per client, not per request
Transport Lifecycle: Transports persist across requests within a session
Error Handling: Comprehensive error handling for all edge cases
Progress Support: Long-running operations can report progress
Clean Architecture: Clear separation between server creation and request handling