|
| 1 | +# Streamable HTTP Transport for MCP |
| 2 | + |
| 3 | +This repository now includes a **Streamable HTTP Transport** implementation that provides an alternative to the stdio-based approach for running MCP servers in AWS Lambda. |
| 4 | + |
| 5 | +## Why Streamable HTTP Transport? |
| 6 | + |
| 7 | +The original stdio-based approach requires creating child processes inside Lambda functions and bridging stdio communication. The Streamable HTTP transport eliminates this complexity by implementing native HTTP communication. |
| 8 | + |
| 9 | +### Architecture Comparison |
| 10 | + |
| 11 | +#### Original Stdio Approach |
| 12 | +``` |
| 13 | +[MCP Client] → [Lambda Invoke API] → [Lambda Function] |
| 14 | + → [stdio bridge] → [Child Process MCP Server] |
| 15 | + → [stdio response] → [Lambda Response] → [MCP Client] |
| 16 | +``` |
| 17 | + |
| 18 | +#### New Streamable HTTP Approach |
| 19 | +``` |
| 20 | +[MCP Client] → [HTTP POST with SigV4] → [Lambda Function URL] |
| 21 | + → [StreamableHTTPServerTransport] → [MCP Tools with Context] |
| 22 | + → [SSE/JSON Response] → [MCP Client] |
| 23 | +``` |
| 24 | + |
| 25 | +## Key Advantages |
| 26 | + |
| 27 | +- Better performance: No child process overhead, faster cold starts |
| 28 | +- Native AWS security: Built-in SigV4 authentication |
| 29 | +- Real-time streaming: Server-Sent Events for notifications |
| 30 | +- Context passing: Clean mechanism to pass Lambda event data to tools |
| 31 | +- Cost effective: Direct Lambda Function URLs, no API Gateway needed |
| 32 | +- Comprehensive error handling, retry logic, session management |
| 33 | + |
| 34 | +## Quick Start |
| 35 | + |
| 36 | +### 1. Install the Transport |
| 37 | + |
| 38 | +```bash |
| 39 | +cd src/typescript-streamable-http |
| 40 | +npm install |
| 41 | +npm run build |
| 42 | +``` |
| 43 | + |
| 44 | +### 2. Run the Examples |
| 45 | + |
| 46 | +```bash |
| 47 | +cd examples/streamable-http |
| 48 | +npm install |
| 49 | + |
| 50 | +# Start server |
| 51 | +npm run dev:server |
| 52 | + |
| 53 | +# In another terminal, start client |
| 54 | +npm run dev:client |
| 55 | +``` |
| 56 | + |
| 57 | +### 3. Deploy to AWS Lambda |
| 58 | + |
| 59 | +The examples include complete deployment instructions for AWS Lambda with Function URLs. |
| 60 | + |
| 61 | +## Implementation Highlights |
| 62 | + |
| 63 | +### Server Side |
| 64 | +```typescript |
| 65 | +import { StreamableHTTPServerTransport, extractContextFiled } from './src/typescript-streamable-http'; |
| 66 | + |
| 67 | +const transport = new StreamableHTTPServerTransport({ |
| 68 | + sessionIdGenerator: () => undefined, // Stateless for Lambda |
| 69 | + enableJsonResponse: false // Use SSE streaming |
| 70 | +}); |
| 71 | + |
| 72 | +// Extract context in MCP tools |
| 73 | +const context = extractContextFiled<UserContext>(mcpServer, 'context'); |
| 74 | +``` |
| 75 | + |
| 76 | +### Client Side |
| 77 | +```typescript |
| 78 | +import { StreamableHTTPClientTransport } from './src/typescript-streamable-http'; |
| 79 | + |
| 80 | +const transport = new StreamableHTTPClientTransport( |
| 81 | + new URL('https://your-function-url.lambda-url.us-west-2.on.aws/mcp'), |
| 82 | + { context: { userId: '123', role: 'admin' } }, // Pass context |
| 83 | + 'us-west-2', |
| 84 | + 'lambda' |
| 85 | +); |
| 86 | +``` |
| 87 | + |
| 88 | +## Documentation |
| 89 | + |
| 90 | +- **[Transport Library README](src/typescript-streamable-http/README.md)** - Complete API documentation |
| 91 | +- **[Examples README](examples/streamable-http/README.md)** - Step-by-step examples |
| 92 | +- **[Server Example](examples/streamable-http/server-example.ts)** - Complete server implementation |
| 93 | +- **[Client Example](examples/streamable-http/client-example.ts)** - Client with streaming support |
| 94 | + |
| 95 | +## Comparison with Existing Approach |
| 96 | + |
| 97 | +| Feature | Stdio Transport | Streamable HTTP Transport | |
| 98 | +|---------|----------------|---------------------------| |
| 99 | +| **Architecture** | Child process + stdio bridge | Native HTTP communication | |
| 100 | +| **Cold Start** | Slower (process spawning) | Faster (direct HTTP) | |
| 101 | +| **Memory Usage** | Higher (multiple processes) | Lower (single process) | |
| 102 | +| **Context Passing** | Complex (environment variables) | Clean (HTTP headers) | |
| 103 | +| **Streaming** | Limited | Full SSE support | |
| 104 | +| **Error Handling** | Basic | Comprehensive with retry | |
| 105 | +| **AWS Integration** | Manual invoke API | Native SigV4 + Function URLs | |
| 106 | +| **Scalability** | Limited by process limits | HTTP connection pooling | |
| 107 | +| **Cost** | Higher (API Gateway often needed) | Lower (direct Function URLs) | |
| 108 | + |
| 109 | +## Migration Guide |
| 110 | + |
| 111 | +### From Stdio to Streamable HTTP |
| 112 | + |
| 113 | +1. **Replace transport imports**: |
| 114 | + ```typescript |
| 115 | + // Old |
| 116 | + import { stdioServerAdapter } from '@aws/run-mcp-servers-with-aws-lambda'; |
| 117 | + |
| 118 | + // New |
| 119 | + import { StreamableHTTPServerTransport } from './src/typescript-streamable-http'; |
| 120 | + ``` |
| 121 | + |
| 122 | +2. **Update server initialization**: |
| 123 | + ```typescript |
| 124 | + // Old - stdio adapter in Lambda handler |
| 125 | + export const handler = (event, context) => { |
| 126 | + return stdioServerAdapter(serverParams, event, context); |
| 127 | + }; |
| 128 | + |
| 129 | + // New - Express app with HTTP transport |
| 130 | + const app = express(); |
| 131 | + const transport = new StreamableHTTPServerTransport({...}); |
| 132 | + app.all('/mcp', (req, res) => transport.handleRequest(req, res)); |
| 133 | + ``` |
| 134 | + |
| 135 | +3. **Update client connection**: |
| 136 | + ```typescript |
| 137 | + // Old - Lambda invoke transport |
| 138 | + const transport = new LambdaFunctionClientTransport({...}); |
| 139 | + |
| 140 | + // New - HTTP transport |
| 141 | + const transport = new StreamableHTTPClientTransport(url, options, region, service); |
| 142 | + ``` |
| 143 | + |
| 144 | +## Production Deployments |
| 145 | + |
| 146 | +The Streamable HTTP transport is already being used in production environments with: |
| 147 | +- **Multi-stage deployments** (alpha, beta, gamma, prod) |
| 148 | +- **Multiple MCP servers** running as separate Lambda functions |
| 149 | +- **Real-time streaming** for long-running operations |
| 150 | +- **Context-aware tools** that access user and request data |
| 151 | +- **Automatic retry and reconnection** for reliability |
| 152 | + |
| 153 | +## Contributing |
| 154 | + |
| 155 | +This transport implementation represents a significant improvement over the stdio approach and is ready for community adoption. The code is production-tested and includes comprehensive examples and documentation. |
| 156 | + |
| 157 | +## Next Steps |
| 158 | + |
| 159 | +1. **Test the examples** locally |
| 160 | +2. **Deploy to AWS Lambda** using the provided instructions |
| 161 | +3. **Integrate into your MCP applications** |
| 162 | +4. **Contribute improvements** back to the community |
| 163 | + |
| 164 | +The Streamable HTTP transport makes MCP with AWS Lambda more performant, scalable, and developer-friendly while maintaining full protocol compatibility. |
0 commit comments