lambda-server

Lambda MCP Server with Response Streaming

This example demonstrates how to deploy a Serverless MCP server to AWS Lambda with Function URL and AWS Lambda response streaming support (no SSE).

Prerequisites

1. AWS CLI configured with credentials

   aws configure

2. AWS SAM CLI installed

   brew install aws-sam-cli  # macOS
   # or
   pip install aws-sam-cli    # Python

3. Node.js 20.x or later

4. Dependencies installed

   cd examples/lambda-server
   npm install

Architecture

The Lambda function uses:

• Lambda Function URL: Direct HTTPS endpoint without API Gateway
• Response Streaming: AWS Lambda response streaming for large responses
• CORS Support: Configured for web clients
• MCP Protocol: Full Model Context Protocol implementation over HTTP JSON-RPC

Quick Start

1. Build the Lambda function

npm run build:handler

2. Deploy to AWS

npm run deploy

This will guide you through the deployment process. Accept the defaults or customize as needed.

For subsequent deployments:

npm run deploy:quick

3. Test the deployed function

npm run test:deployed

Local Testing

1. Start local Lambda runtime

npm run local

This starts SAM local Lambda runtime on http://localhost:3001

2. In another terminal, run the test client

npm run test:local

Development Workflow

Available Scripts

• npm run build - Build both handler and test client
• npm run build:handler - Build Lambda handler only
• npm run build:client - Build test client only
• npm run deploy - Deploy with guided configuration
• npm run deploy:quick - Deploy using saved configuration
• npm run local - Start local Lambda runtime
• npm run test:local - Test against local Lambda
• npm run test:deployed - Test against deployed Lambda
• npm run test:client -- <url> - Test specific Lambda URL
• npm run logs - Stream CloudWatch logs
• npm run validate - Validate SAM template
• npm run clean - Clean build artifacts

Testing the MCP Server

The test client (test-client.ts) demonstrates:

1. Health Check: Tests basic connectivity
2. MCP Protocol: Tests initialize, tools, resources, and prompts
3. Tool Execution: Calls echo, calculate, and aws-info tools
4. Resource Reading: Fetches Lambda function information
5. Performance Testing: Concurrent request testing with --perf flag

Manual Testing with curl

# Get the function URL from deployment output or AWS Console
FUNCTION_URL="https://xxxxx.lambda-url.us-east-1.on.aws/"

# Test health endpoint
curl -H "Accept: application/json" $FUNCTION_URL

# Test MCP request
curl -X POST $FUNCTION_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Test tool execution
curl -X POST $FUNCTION_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"echo","arguments":{"message":"Hello Lambda!"}},"id":2}'

Monitoring

CloudWatch Logs

# Stream logs in real-time
npm run logs

# Or use AWS CLI
aws logs tail /aws/lambda/serverless-mcp-dev --follow

Metrics

View metrics in AWS Console:

• Lambda > Functions > serverless-mcp-dev > Monitoring

Key metrics:

• Invocations
• Duration
• Errors
• Throttles
• Concurrent executions

Configuration

SAM Template (template.yaml)

• Runtime: Node.js 20.x
• Memory: 512 MB (adjustable)
• Timeout: 30 seconds (max for Function URL streaming)
• CORS: Configured for all origins (customize for production)

Environment Variables

Set in template.yaml:

Environment:
  Variables:
    NODE_ENV: dev
    LOG_LEVEL: INFO
    CUSTOM_VAR: value

Production Considerations

1. Authentication: Add authentication to Function URL

   FunctionUrlConfig:
     AuthType: AWS_IAM  # or use custom authorizer

2. CORS: Restrict origins for production

   Cors:
     AllowOrigins:
       - 'https://your-domain.com'

3. Monitoring: Set up CloudWatch alarms

   • High error rate
   • High latency
   • Throttling

4. Cost Optimization:

   • Adjust memory size based on usage
   • Enable reserved concurrency for predictable traffic
   • Use provisioned concurrency for low latency

Troubleshooting

Response streaming not working

• Ensure Lambda function has response streaming enabled
• Check that InvokeMode: RESPONSE_STREAM is set in template
• Verify Node.js 20.x runtime (streaming requires Node 18+)

Request timeouts

• Lambda Function URL has 30-second timeout
• Check Lambda function logs for errors
• Verify request/response format matches JSON-RPC 2.0

CORS issues

• Verify CORS configuration in template.yaml
• Check browser console for specific CORS errors
• Test with curl to isolate client issues

MCP protocol errors

• Ensure requests follow JSON-RPC 2.0 format
• Check that all required MCP fields are present
• Verify tool/resource/prompt names are correct

Clean Up

Remove the deployed stack:

aws cloudformation delete-stack --stack-name serverless-mcp-stack

Or keep the stack and just clean local artifacts:

npm run clean