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 toolget_server_info: Returns server informationlong_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
Environment Variables
PORT: Server port (default: 3001)DEBUG: Enable debug logging (trueby default)
Endpoints
POST /mcp: Handle JSON-RPC requestsGET /mcp: Handle SSE streamingDELETE /mcp: Terminate sessionsGET /health: Health check endpoint