cloudmcp

README

Cloud-Native Serverless Model-Context-Protocol (MCP) Server

Deploy Model Context Protocol servers to AWS Lambda with zero infrastructure hassle

CloudMCP is a Golang library that simplifies the deployment of Model Context Protocol (MCP) servers to AWS Lambda behind an API Gateway, using AWS CDK for infrastructure-as-code. It bridges the gap between Model Context Protocol and AWS serverless infrastructure. Write your MCP tools in Go, deploy them as Lambda functions in minutes. No boilerplate, no infrastructure headaches.

Why cloudmcp library?

Building MCP servers is easy. Deploying them to production as a final product with proper authentication, scaling, and monitoring takes real effort. This library removes that friction and gives you a production-ready setup out of the box.

What you get:

• Built on the official Go MCP SDK ensuring strict protocol correctness, long-term compatibility, and highly performant, production-grade MCP servers by default.
• Serverless-first architecture with instant autoscaling, zero server management, pay-only-for-use economics, and a clean developer experience focused entirely on your MCP logic rather than infrastructure.
• Production-grade security using battle tests authentication and authorization layers at AWS API Gateway.
• Pluggable identity providers with seamless JWT validation using AWS Cognito, Auth0, and others.
• AWS IAM-based security for fine-grained permissions, secure service interactions and cloud-native depolyments.
• Infrastructure as Code throught version-controlled, reproducible deployments using AWS CDK.
• Observability out of the box CloudWatch logs, metrics, and structured tracing for every MCP request.
• One-command deployment ship new MCP tools and servers globally with nearly no operational burden.
• Zero-effort portability to server (long-running) mode seamlessly switch from Lambda to a persistent server deployment when your scale or latency profile demands it, with no code changes.

Quick Start

go get github.com/fogfish/cloudmcp

See examples/helloworld for a complete working example to start with. Below is a minimalistic skeleton of the server.

Define your MCP tool, add a deployment configuration, run cdk deploy. Your MCP server is now live on API Gateway, ready for AI assistants to call.

import (
  "github.com/modelcontextprotocol/go-sdk/mcp"
  "github.com/fogfish/cloudmcp"
)

// define your tool using **offical Golang SDK**
func Sayer(ctx context.Context, req *mcp.CallToolRequest, input Input) (*mcp.CallToolResult, Output, error) {
  //...
}

// define your server using **offical Golang SDK**
func HelloWorld() (*mcp.Server, error) {
  server := mcp.NewServer(/* ... */)
  return server, nil
}

// deploy MPC server as serverless gateway
func main() {
  cloudmcp.New(server.HelloWorld).
    Hostless().
    AccessApiKey("access", "secret").
    Build()
}

Serverless MCPs

The library provides both a high-level API for deploying an entire MCP server as Lambda functions with minimal configuration, and a low-level API for advanced, fine-grained control of your infrastructure. Both approaches require a basic understanding of AWS CDK v2, but the low-level API assumes you are writing full IaC, while the high-level API offers a simple yet powerful abstraction that dramatically reduces configuration complexity. Usage of low-level api is required when you are integrating MCPs into exiting cloud-native application, for standalong MCP deployments a high-level api sufficient.

The high-level API uses a builder pattern, where you simply supply a server factory function and the library takes care of wiring, packaging, and deploying your MCP server to Lambda (it auto generates lambda code):

cloudmcp.New( func() (*mcp.Server, error) )

It is only mandatory to configure hosting and security options before deployment.

Hosting

The MCP server is hosted behind AWS API Gateway. You can deploy it using the default hostname and TLS certificate (so-called hostless mode), or provide a custom hostname and TLS certificate. Using a custom domain requires proper configuration of the DNS zone in AWS Route 53 and provisioning the TLS certificate via AWS Certificate Manager (see the official AWS documentation for detailed instructions).

• .Hostless() use default hostname as the endpoint
• .Host(domain, tlsarn) configure custom endpoint

Security

Choose your security model with a single method call:

• .AccessPublic() - No authentication (development only)
• .AccessApiKey(access, secret) - Simple key-based auth
• .AccessJWT(issuer, audiences...) - Industry-standard JWT tokens
• .AccessAwsCognito(poolArn, clients...) - Integrate with AWS Cognito
• .AllowAccessIAM(authorizer, principal) - AWS-to-AWS secure communication

IAM Authentication

Since the library enhances auth options with ApiKey and IAM, it offers a simple client library to create a MCP client transport with build-in authentication configuration. See pkg/auth

import (
  "github.com/fogfish/cloudmcp/pkg/auth"
)

transport, err := auth.NewTransportIAM(/* ... */)

client := mcp.NewClient(/* ... */)
client.Connect(context.Backgorund(), transport, nil)

CloudWatch Logs

Automatic log group creation with configurable retention. Logs appear at /app/{ServerName} with 5 days retention (adjustable).

Examples

• helloworld - Minimal MCP Server deployment using high-level api
• serverless - Advanced patterns with custom CDK configuration using low-level api

Both examples include working code and deployable with single cdk deploy command.

Use in VS Code

Integration of serverless MCPs is straightforwards as any other, withing mcp.json

{
  "servers": {
    "helloworld": {
      "type": "http",
      "url": "https://0000000000.execute-api.eu-west-1.amazonaws.com/api/helloworld",
      "headers": {
        "Authorization": "Basic YWNjZXNzOnNlY3JldA"
      }
    },
  }
}

When to use cloudmcp library

✅ You need MCP servers in production, not just local development
✅ You want serverless benefits: auto-scaling, pay-per-use, zero maintenance
✅ You use AWS or are willing to deploy there
✅ You want infrastructure as code with AWS CDK

❌ You need WebSocket/SSE streaming (Lambda proxy limitations)
❌ You're committed to a different cloud provider

Requirements

• Go 1.25+
• AWS Account
• AWS CDK CLI: npm install -g aws-cdk
• Configured AWS credentials

Related Projects

• Model Context Protocol - Official MCP specification
• MCP Go SDK - Official Go MCP implementation
• Scud - Serverless CDK utilities (cloudmcp dependency)

Contributing

iq is MIT licensed and accepts contributions via GitHub pull requests:

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

License

Documentation

Index

• Constants
• type Factory
• type Function
  • func NewFunction[A, B any](scope constructs.Construct, id *string, spec *FunctionProps[A, B]) *Function[A, B]
  • func (c *Function[A, B]) AllowAccessApiKey(api *scud.AuthorizerBasic)
  • func (c *Function[A, B]) AllowAccessIAM(api *scud.AuthorizerIAM, principal awsiam.IGrantable)
  • func (c *Function[A, B]) AllowAccessJWT(api *scud.AuthorizerJwt, scope ...string)
  • func (c *Function[A, B]) AllowAccessPublic(api *scud.AuthorizerPublic)
• type FunctionProps
  • func NewFunctionProps[A, B any](f Lambda[A, B], about string, props *scud.FunctionGoProps) *FunctionProps[A, B]
  • func (f *FunctionProps[A, B]) ForceAutoGen() *FunctionProps[A, B]
• type Gateway
  • func New(f Factory) *Gateway
  • func (c *Gateway) AccessApiKey(access, secret string) *Gateway
  • func (c *Gateway) AccessAwsCognito(cognitoArn string, clients ...string) *Gateway
  • func (c *Gateway) AccessJWT(issuer string, audience ...string) *Gateway
  • func (c *Gateway) AccessPublic() *Gateway
  • func (c *Gateway) Build()
  • func (c *Gateway) Gateway(props *scud.GatewayProps) *Gateway
  • func (c *Gateway) Host(host, certificate string) *Gateway
  • func (c *Gateway) Hostless() *Gateway
• type Lambda
• type Server
  • func NewServer(scope constructs.Construct, id *string, spec *ServerProps) *Server
  • func (c *Server) AllowAccessApiKey(api *scud.AuthorizerBasic)
  • func (c *Server) AllowAccessIAM(api *scud.AuthorizerIAM, principal awsiam.IGrantable)
  • func (c *Server) AllowAccessJWT(api *scud.AuthorizerJwt, scope ...string)
  • func (c *Server) AllowAccessPublic(api *scud.AuthorizerPublic)
• type ServerProps
  • func NewServerProps(f Factory, props *scud.FunctionGoProps) *ServerProps
  • func (f *ServerProps) ForceAutoGen() *ServerProps

Constants

const Version = "v0.0.1"

Types

type Factory

type Factory = func() (*mcp.Server, error)

Factory is a function that constructs instance of MCP Server.

func HelloWorld() (*mcp.Server, error) {
	server := mcp.NewServer(...)
	mcp.AddTool(server, ...)
	return server, nil
}

type Function

type Function[A, B any] struct {
	Function awslambda.Function
	// contains filtered or unexported fields
}

L3 Construct for MCP Tool Function as AWS Lambda function. This construct assumes a function is running as an instance of MCP Server.

func NewFunction

func NewFunction[A, B any](scope constructs.Construct, id *string, spec *FunctionProps[A, B]) *Function[A, B]

Defines MCP Tool Function as a Lambda function.

func (*Function[A, B]) AllowAccessApiKey

func (c *Function[A, B]) AllowAccessApiKey(api *scud.AuthorizerBasic)

Grants access to the function via given API key authorizer.

func (*Function[A, B]) AllowAccessIAM

func (c *Function[A, B]) AllowAccessIAM(api *scud.AuthorizerIAM, principal awsiam.IGrantable)

Grants access to the function via given IAM authorizer.

func (*Function[A, B]) AllowAccessJWT

func (c *Function[A, B]) AllowAccessJWT(api *scud.AuthorizerJwt, scope ...string)

Grants access to the function via given JWT authorizer.

func (*Function[A, B]) AllowAccessPublic

func (c *Function[A, B]) AllowAccessPublic(api *scud.AuthorizerPublic)

Grants public access to the function via given public authorizer.

type FunctionProps

type FunctionProps[A, B any] struct {
	*scud.FunctionGoProps
	Handler Lambda[A, B]
	About   string
	AutoGen bool
}

FunctionProps defines properties for MCP Tool Function as a Lambda function. The properties are type-safe declaration for MCP tool inptut and output types. The construct assumes a function is running as an instance of MCP Server, it performs automatic code generation for binding the function into MCP Server.

func NewFunctionProps

func NewFunctionProps[A, B any](f Lambda[A, B], about string, props *scud.FunctionGoProps) *FunctionProps[A, B]

Helper for NewFunctionProps to support automatic inference of types from function

func (*FunctionProps[A, B]) ForceAutoGen

func (f *FunctionProps[A, B]) ForceAutoGen() *FunctionProps[A, B]

Force regeneration of the function binding code on each deployment.

type Gateway

type Gateway struct {
	// contains filtered or unexported fields
}

Serverless MCP Gateway, wraps MCP Server as defined by official Go SDK into AWS API Gateway and Lambda deployment.

func New

func New(f Factory) *Gateway

Creates new Gateway builder for given MCP Server factory

func (*Gateway) AccessApiKey

func (c *Gateway) AccessApiKey(access, secret string) *Gateway

Configures gateway with API Key access, using basic digest authentication with access and secret keys.

func (*Gateway) AccessAwsCognito

func (c *Gateway) AccessAwsCognito(cognitoArn string, clients ...string) *Gateway

Configures gateway with AWS Cognito access, using given user pool ARN and optional list of app clients.

func (*Gateway) AccessJWT

func (c *Gateway) AccessJWT(issuer string, audience ...string) *Gateway

Configures gateway with JWT access, using given issuer and optional list of audiences.

func (*Gateway) AccessPublic

func (c *Gateway) AccessPublic() *Gateway

Configures gateway with public access (no authentication).

func (*Gateway) Build

func (c *Gateway) Build()

func (*Gateway) Gateway

func (c *Gateway) Gateway(props *scud.GatewayProps) *Gateway

Configures gateway with custom properties.

func (*Gateway) Host

func (c *Gateway) Host(host, certificate string) *Gateway

Configures gateway with custom domain and TLS certificate ARN.

func (*Gateway) Hostless

func (c *Gateway) Hostless() *Gateway

Configures gateway without custom domain, default API Gateway host will be used.

type Lambda

type Lambda[A, B any] = func(context.Context, *mcp.CallToolRequest, A) (*mcp.CallToolResult, B, error)

Signature for type-safe entry point to lambda function

type Server

type Server struct {
	Function awslambda.Function
	// contains filtered or unexported fields
}

L3 Construct for MCP Server as AWS Lambda function. This construct assumes a function is running an instance of MCP Server.

func NewServer

func NewServer(scope constructs.Construct, id *string, spec *ServerProps) *Server

Defines MCP Server as a Lambda function.

func (*Server) AllowAccessApiKey

func (c *Server) AllowAccessApiKey(api *scud.AuthorizerBasic)

Grants access to the server via given API key authorizer.

func (*Server) AllowAccessIAM

func (c *Server) AllowAccessIAM(api *scud.AuthorizerIAM, principal awsiam.IGrantable)

Grants access to the server via given IAM authorizer.

func (*Server) AllowAccessJWT

func (c *Server) AllowAccessJWT(api *scud.AuthorizerJwt, scope ...string)

Grants access to the server via given JWT authorizer.

func (*Server) AllowAccessPublic

func (c *Server) AllowAccessPublic(api *scud.AuthorizerPublic)

Grants public access to the server via given public authorizer.

type ServerProps

type ServerProps struct {
	*scud.FunctionGoProps
	Factory Factory
	AutoGen bool
}

ServerProps defines properties for MCP Server as a Lambda function. This construct assumes a function is running an instance of MCP Server.

func NewServerProps

func NewServerProps(f Factory, props *scud.FunctionGoProps) *ServerProps

Helper utility to bind scud.FunctionGoProps with MCP Server Factory.

func (*ServerProps) ForceAutoGen

func (f *ServerProps) ForceAutoGen() *ServerProps

Force regeneration of the server binding code on each deployment.