Serverless MCP

🚀 Serverless MCP

This project offers a serverless implementation of the Model Context Protocol (MCP) using AWS Lambda, CloudFront, and Cognito authentication. It provides a complete cloud - based infrastructure for hosting MCP servers, featuring OAuth 2.0 authentication, real - time streaming via Server - Sent Events with JSON - RPC 2.0 messaging format, and a scalable serverless architecture. The implementation also includes RFC - compliant OAuth 2.0 support and is compatible with the official Model Context Protocol TypeScript SDK.

🚀 Quick Start

This Serverless MCP project provides a serverless solution for the Model Context Protocol. To get started, you need to complete the installation and deployment steps as described in the following sections.

✨ Features

• MCP Protocol Implementation: Full support for the Model Context Protocol, along with associated tools and resources.
• Serverless Architecture: Utilizes AWS Lambda functions with CloudFront distribution.
• OAuth 2.0 Authentication: Ensures secure authentication through AWS Cognito.
• Real - time Streaming: Supports Server - Sent Events (SSE) for live communication.
• Session Management: Handles both stateful and stateless sessions.
• Custom Domain: Includes SSL certificates and Route 53 DNS configuration.
• GitHub Actions Deployment: Features an OIDC - based CI/CD pipeline.

📦 Installation

Prerequisites

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

Steps

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

💻 Usage Examples

MCP Server Endpoints

Once deployed, your MCP server will be accessible 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:

Basic Usage

{
    "name": "get_today_date"
}

Advanced Usage

{
    "name": "get_dimension_values", 
    "arguments": {
        "dimensionKey": "SERVICE",
        "startDate": "2024-01-01",
        "endDate": "2024-01-31"
    }
}

{
    "name": "get_tag_values",
    "arguments": {
        "tagKey": "Environment", 
        "startDate": "2024-01-01",
        "endDate": "2024-01-31"
    }
}

{
    "name": "get_cost_and_usage",
    "arguments": {
        "startDate": "2024-01-01",
        "endDate": "2024-01-31",
        "granularity": "MONTHLY",
        "groupBy": [{"Type": "DIMENSION", "Key": "SERVICE"}]
    }
}

{
    "name": "get_cost_forecast",
    "arguments": {
        "startDate": "2024-02-01", 
        "endDate": "2024-02-29",
        "metric": "UNBLENDED_COST"
    }
}

{
    "name": "get_cost_and_usage_comparisons",
    "arguments": {
        "baseStartDate": "2024-01-01",
        "baseEndDate": "2024-01-31", 
        "comparisonStartDate": "2024-02-01",
        "comparisonEndDate": "2024-02-29"
    }
}

{
    "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: A dynamic greeting resource.
  • Template: greeting://[name]
  • Example: greeting://world returns "Hello, world!"

Client Connection

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

📚 Documentation

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

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

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

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

📄 License

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