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

Related MCP server: AWS CodePipeline MCP Server

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:

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

2. Install dependencies:

pnpm install

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

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',
};

Development

Build and Test

# Build the project
pnpm build

# Watch for changes during development
pnpm watch

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with UI
pnpm test:ui

Code Quality

# Lint code
pnpm lint

# Fix linting issues
pnpm lint:fix

# Format code
pnpm format

# Check formatting
pnpm format:check

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

# Deploy both stacks
pnpm cdk deploy --all

# Deploy specific stack
pnpm cdk deploy serverless-mcp
pnpm cdk deploy serverless-mcp-github-oidc

# Preview changes
pnpm cdk diff

# Generate CloudFormation templates
pnpm cdk synth

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):

pnpm cdk deploy serverless-mcp-github-oidc

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:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPTransport('https://your-domain.com/mcp');

const client = new Client(
  { name: 'my-client', version: '1.0.0' },
  { capabilities: {} }
);

await client.connect(transport);

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