serverless

This MCP server is a serverless implementation of the Model Context Protocol (MCP) designed to run on AWS using Lambda functions, a CloudFront distribution, and Cognito authentication. It provides real-time streaming via Server-Sent Events and communicates using the JSON-RPC 2.0 messaging format. Once deployed, your MCP endpoint will be available at the configured domain under /mcp, with authentication handled by Cognito and all traffic routed through CloudFront. The server supports both stateful and stateless session handling and includes an OAuth 2.0 setup compatible with RFC 8414, RFC 7591, and RFC 9728. A custom transport integrates with the official MCP TypeScript SDK for seamless client communication.

Prerequisites:

• Node.js 22
• pnpm >= 10.12
• AWS CLI configured with appropriate permissions
• A registered domain name with a Route 53 hosted zone

Installation and setup:

1. Clone the repository and install dependencies

git clone https://github.com/hteek/serverless-mcp.git
cd serverless-mcp
pnpm install

2. Configure domain and Cognito settings

• Edit config/default.ts and set domainName, hostedZoneId, and Cognito-related settings as shown in the README:

export default {
  domainName: 'your-domain.com',
  github: {
    owner: 'your-github-username',
    repo: 'your-repo-name',
  },
  hostedZoneId: 'YOUR_ROUTE53_HOSTED_ZONE_ID',
  project: 'your-project-name',
};

3. Bootstrap and build the CDK project, then synthesize CloudFormation

pnpm build
pnpm cdk synth

4. Deploy to AWS (requires AWS credentials and proper IAM permissions)

pnpm cdk deploy --all

5. Validate deployment

• Confirm the CloudFront distribution, Lambda functions, Cognito user pool, and DynamoDB table are created
• Ensure DNS records for https://your-domain.com and authentication endpoint are correctly set up

Notes:

• If you are integrating with GitHub Actions, ensure the OIDC stack is deployed first as described in the deployment docs.

Tips and common issues:

• Ensure AWS credentials are correctly configured and have permissions to create Lambda, CloudFront, Cognito, and DynamoDB resources.
• The environment variables in the mcp_config section should be filled with real values or placeholders that your deployment process can substitute during CDK synthesis.
• If you encounter domain or DNS issues, verify that the Route 53 hosted zone ID and the domain ownership configuration are correct.
• OAuth 2.0 configuration relies on Cognito; ensure the user pool and app client are created and the app client has proper callback and sign-out URLs configured.
• For local testing, you may simulate the MCP client using the provided TypeScript SDK and transport example in the README, connecting to https://your-domain.com/mcp once deployed.