Serverless MCP

Serverless MCP

A serverless implementation of the Model Context Protocol (MCP) using AWS Lambda, CloudFront, and Cognito authentication. This project provides a complete infrastructure for hosting MCP servers in the cloud with OAuth 2.0 authentication, real-time streaming via Server-Sent Events with JSON-RPC 2.0 messaging format, and scalable serverless architecture. The implementation includes RFC-compliant OAuth 2.0 support with OAuth 2.0 Authorization Server Metadata (RFC 8414), OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591), and OAuth 2.0 Protected Resource Metadata (RFC 9728). Features a custom transport implementation compatible with the official Model Context Protocol TypeScript SDK.

Features

• MCP Protocol Implementation: Full support for Model Context Protocol with tools and resources
• Serverless Architecture: AWS Lambda functions with CloudFront distribution
• OAuth 2.0 Authentication: Secure authentication using AWS Cognito
• Real-time Streaming: Server-Sent Events (SSE) support for live communication
• Session Management: Stateful and stateless session handling
• Custom Domain: SSL certificates and Route 53 DNS configuration
• GitHub Actions Deployment: OIDC-based CI/CD pipeline

Architecture

The project consists of two main CDK stacks:

1. ServerlessMcpStack: Core infrastructure including Lambda functions, CloudFront distribution, Cognito user pool, and DynamoDB table
2. GitHubOidcStack: GitHub Actions OIDC provider for secure deployments

Prerequisites

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

Installation

1. Clone the repository:

2. Install dependencies:

3. Configure your domain settings in config/default.ts:

Development

Build and Test

Code Quality

Deployment

Prerequisites

1. Ensure your AWS credentials are configured
2. Verify your domain is registered and the hosted zone ID is correct
3. Build the project: pnpm build

Manual Deployment

GitHub Actions Deployment

This project includes three GitHub Actions workflows for automated deployment:

1. Continuous Integration and Deployment (ci.yml)

Trigger: Pushes to main branch and pull requests

Jobs:

• CI Pipeline: Runs build, lint, and tests on all pushes and PRs
• Automated Deployment: Deploys to AWS when changes are pushed to main

Environment: Uses development environment with AWS_ACCOUNT variable

2. Manual Deployment (manual-deploy.yml)

Trigger: Manual workflow dispatch via GitHub UI

Usage: For ad-hoc deployments without code changes

3. Reusable Deploy Workflow (deploy.yml)

Purpose: Shared deployment logic used by other workflows

Features:

• OIDC authentication with AWS
• Installs dependencies and builds project
• Deploys using CDK with no approval required

Initial Setup

1. Deploy GitHub OIDC Stack (one-time setup):

2. Configure GitHub Environment:
   • Go to your GitHub repository → Settings → Environments
   • Create a development environment
   • Add environment variable: AWS_ACCOUNT with your AWS account ID
3. Verify Deployment:
   • The GitHub OIDC stack creates an IAM role: github-actions-role
   • This role has the necessary permissions for CDK deployment
   • No long-lived AWS credentials needed in GitHub secrets

Deployment Process

Automatic Deployment:

1. Push changes to main branch
2. CI workflow runs: build → lint → test → deploy
3. Deployment uses OIDC to assume AWS role
4. CDK deploys the serverless-mcp stack

Manual Deployment:

1. Go to Actions tab in GitHub repository
2. Select "manual deploy" workflow
3. Click "Run workflow" on main branch

Monitoring Deployments

• GitHub Actions: View workflow runs in the Actions tab
• AWS CloudFormation: Check stack status in AWS console
• CloudWatch: Monitor Lambda function logs and metrics

Usage

MCP Server Endpoints

Once deployed, your MCP server will be available at:

• Main endpoint: https://your-domain.com/mcp
• Authentication: https://auth.your-domain.com

Available MCP Tools

The server implements the following AWS Cost Explorer tools:

• get_today_date: Get the current date to help with relative date queries
  { "name": "get_today_date" }
• get_dimension_values: Get available values for AWS Cost Explorer dimensions (SERVICE, REGION, etc.)
  { "name": "get_dimension_values", "arguments": { "dimensionKey": "SERVICE", "startDate": "2024-01-01", "endDate": "2024-01-31" } }
• get_tag_values: Get available values for a specific tag key
  { "name": "get_tag_values", "arguments": { "tagKey": "Environment", "startDate": "2024-01-01", "endDate": "2024-01-31" } }
• get_cost_and_usage: Retrieve AWS cost and usage data with filtering and grouping
  { "name": "get_cost_and_usage", "arguments": { "startDate": "2024-01-01", "endDate": "2024-01-31", "granularity": "MONTHLY", "groupBy": [{"Type": "DIMENSION", "Key": "SERVICE"}] } }
• get_cost_forecast: Generate cost forecasts based on historical usage patterns
  { "name": "get_cost_forecast", "arguments": { "startDate": "2024-02-01", "endDate": "2024-02-29", "metric": "UNBLENDED_COST" } }
• get_cost_and_usage_comparisons: Compare costs between two time periods
  { "name": "get_cost_and_usage_comparisons", "arguments": { "baseStartDate": "2024-01-01", "baseEndDate": "2024-01-31", "comparisonStartDate": "2024-02-01", "comparisonEndDate": "2024-02-29" } }
• get_cost_comparison_drivers: Analyze what drove cost changes between periods
  { "name": "get_cost_comparison_drivers", "arguments": { "baseStartDate": "2024-01-01", "baseEndDate": "2024-01-31", "comparisonStartDate": "2024-02-01", "comparisonEndDate": "2024-02-29" } }

Available MCP Resources

• greeting: Dynamic greeting resource
  • Template: greeting://[name]
  • Example: greeting://world returns "Hello, world!"

Client Connection

Connect to your MCP server using any MCP-compatible client:

Configuration

Environment-Specific Settings

Create environment-specific configuration files in the config/ directory:

• config/development.ts
• config/production.ts
• config/staging.ts

CDK Context

Modify cdk.json to adjust CDK feature flags and behavior.

Monitoring and Debugging

• CloudWatch Logs: Lambda function logs are automatically sent to CloudWatch
• AWS X-Ray: Distributed tracing is enabled for performance monitoring
• Metrics: Custom metrics are collected using AWS Lambda Powertools

Security

• Authentication: OAuth 2.0 with AWS Cognito
• HTTPS: All traffic encrypted with SSL/TLS
• IAM: Least privilege access policies
• Session Management: Secure session handling with validation

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make your changes and add tests
4. Run linting and tests: pnpm lint && pnpm test
5. Commit your changes: git commit
6. Push and create a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

1. Check the documentation for development guidance
2. Open an issue on GitHub
3. Review CloudWatch logs for debugging information

Useful Commands

• pnpm build - Compile TypeScript to JavaScript
• pnpm watch - Watch for changes and compile
• pnpm test - Run Vitest unit tests
• pnpm cdk deploy - Deploy infrastructure to AWS
• pnpm cdk diff - Compare deployed stack with current state
• pnpm cdk synth - Generate CloudFormation templates
• pnpm cdk destroy - Remove all AWS resources