cloudmcp

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 14 Imported by: 0

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 runs Model Context Protocol (MCP) servers, written with the official Go SDK, on AWS Lambda behind AWS API Gateway, using AWS CDK for infrastructure-as-code. Write your MCP tools in Go, write a one-line Lambda main, deploy with cdk deploy.

Why cloudmcp library?

Building MCP servers is easy. Deploying them to production with proper authentication, scaling, and monitoring takes real effort. This library removes that friction.

What you get:

  • Built on the official Go MCP SDK, tools are plain go-sdk tools, they never import cloudmcp.
  • Serverless-first architecture with instant autoscaling, zero server management and pay-only-for-use economics.
  • Security at AWS API Gateway: API keys, JWT (Cognito, Auth0, ...), AWS IAM or your own Lambda authorizer. The caller's identity reaches tools as go-sdk's req.Extra.TokenInfo.
  • Tools per caller: the server is built once, tools are filtered per request (e.g. read-only callers see read-only tools).
  • MCP authorization compliance (opt-in): protected resource metadata (RFC 9728) and 401 challenge for OAuth-capable clients.
  • Observability: CloudWatch metrics (EMF) per method and tool, structured JSON logs.
  • Infrastructure as Code with AWS CDK constructs that drop into an existing application.
  • Portability to server mode: the same server runs as long-running HTTP server with serve.ListenAndServe.

Quick Start

go get github.com/fogfish/cloudmcp

See examples/helloworld for a complete working example. Define your MCP server using the official Go SDK:

package server

func New() *mcp.Server {
  server := mcp.NewServer(&mcp.Implementation{Name: "hello world", Version: "v1.0.0"}, nil)
  mcp.AddTool(server, &mcp.Tool{Name: "sayer", Description: "says Hello World!"}, Sayer)
  return server
}

Write the Lambda function's main (e.g. cmd/mcp/main.go), dependencies are injected by your code:

package main

import (
  "github.com/aws/aws-lambda-go/lambda"
  "github.com/fogfish/cloudmcp/serve"
)

func main() {
  lambda.Start(serve.Handler(serve.Static(server.New())))
}

Deploy it (CDK application, e.g. main.go with cdk.json), run cdk deploy:

func main() {
  cloudmcp.New("cmd/mcp").
    Hostless().
    AccessApiKey("access", "secret").
    Build()
}

The library has two parts:

Runtime

serve.Handler(factory, options...) is the Lambda handler. The factory has go-sdk's own shape func(*http.Request) *mcp.Server (the argument of mcp.NewStreamableHTTPHandler):

  • serve.Static(server) serves the same server to every request.
  • serve.Filter(server, predicate) builds the server once and chooses tools per request, the predicate receives the tool and the caller's TokenInfo. Hidden tools are absent from tools/list and fail tools/call as unknown tools.
  • serve.Tool(tool, handler) is the server with a single typed tool (e.g. worker of the dispatcher).
readonly := func(t *mcp.Tool, info *auth.TokenInfo) bool {
  if info != nil && slices.Contains(info.Scopes, "write") {
    return true
  }
  return t.Annotations != nil && t.Annotations.ReadOnlyHint
}

lambda.Start(serve.Handler(serve.Filter(server.New(), readonly)))

The handler accepts API Gateway events of payload format 1.0 and 2.0 (detected from the event; multi-value headers and query parameters are preserved). Servers are stateless and respond with JSON, Lambda cannot keep sessions or stream events.

Identity

The caller's identity, as established by API Gateway, is mapped to go-sdk's auth.TokenInfo, tools read it from req.Extra.TokenInfo. Nothing in the request body or headers can change it. TokenInfo is produced for every request through API Gateway, including Basic (API key) and anonymous (public) calls, whose UserID is empty.

TokenInfo Source
UserID Lambda authorizer context principal, sub or principalId; JWT claim sub; IAM user ARN
Scopes Lambda authorizer context scope or scopes (space separated string or list); JWT scopes
Extra every key of the Lambda authorizer context, JWT claims at claims, path parameters at path
Expiration deadline of the Lambda invocation
func Tool(ctx context.Context, req *mcp.CallToolRequest, in Input) (*mcp.CallToolResult, Output, error) {
  info := req.Extra.TokenInfo
  instance := info.Extra["path"].(map[string]string)["instance"]
  // ...
}

Use serve.WithIdentity(func(*serve.Identity) *auth.TokenInfo) to customize the mapping, or serve.WithVerifier(verifier) to verify bearer tokens in the function (public routes, server mode).

Errors

  • A body that is not JSON-RPC is answered with HTTP 400 and JSON-RPC error -32700.
  • GET and DELETE are answered with HTTP 405 and Allow: POST.
  • Panics (in the factory or in tools) are recovered, logged and answered with HTTP 500 / JSON-RPC error -32603.
  • serve.WithDebug() logs JSON-RPC method and id of each request; parameters, which may hold user data, are never logged.

Observability

  • serve.WithMetrics(namespace) emits CloudWatch metrics using Embedded Metric Format: Requests, Errors and Latency with dimensions [Method] and [Method, Tool]. A request is an error if the HTTP status is not 2xx, the JSON-RPC response is an error, or the tool result has isError.
  • serve.WithJSONLogs(level) writes structured JSON logs to stdout and makes it the default slog logger; serve.WithLogger(logger) uses your own logger.

Server mode

The same factory runs as long-running HTTP server, with go-sdk defaults (sessions, event streams):

serve.ListenAndServe(":8080", serve.Static(server.New()))

serve.HTTPHandler(factory, options...) returns the http.Handler to embed into your own server.

MCP authorization

OAuth-capable MCP clients discover how to authenticate from a 401 with WWW-Authenticate: Bearer resource_metadata="..." and protected resource metadata (RFC 9728). API Gateway's own 401 cannot carry the challenge, so the function is the resource server:

serve.Handler(factory,
  serve.WithResourceServer(serve.ResourceServer{
    Metadata: &oauthex.ProtectedResourceMetadata{
      Resource:             "https://mcp.example.com/mcp",
      AuthorizationServers: []string{"https://auth.example.com"},
    },
    // with annotating Lambda authorizer, which always allows and passes its decision
    Authenticated: func(info *auth.TokenInfo) bool { return info.Extra["decision"] == "allow" },
  }),
)

The route is either public with serve.WithVerifier verifying tokens in the function, or protected by an annotating Lambda authorizer. Route the metadata to the function with .ResourceMetadata() (high-level) or Server.ServeResourceMetadata (low-level).

High-level API

The builder deploys a standalone stack: API Gateway, authorizer, the server function and the log group /app/{name} (5 days retention).

cloudmcp.New("cmd/mcp") takes the path of the server's main package relative to the main module of the CDK application (.Module(...) overrides the module). Configure hosting and security before .Build().

  • .Name(name) the stack name, default is the base name of the path
  • .Route(route) the route, default /mcp, may have path parameters (/{instance}) or be the root /
  • .Function(props) properties of the function (memory, environment, ...)
  • .Hostless() default API Gateway host, .Host(domain, tlsarn) custom domain, .Gateway(props) custom properties
  • .Cors(origins...) CORS for browser MCP clients, allowing MCP headers (Mcp-Session-Id, Mcp-Protocol-Version)
  • .ResourceMetadata() public routes of protected resource metadata

Security:

  • .AccessPublic() no authentication
  • .AccessApiKey(access, secret) access/secret keys as Basic credentials
  • .AccessJWT(issuer, audiences...) JWT tokens
  • .AccessAwsCognito(poolArn, clients...) AWS Cognito
  • .AccessLambda("cmd/authorizer", props) your own Lambda authorizer (see scud/authorizer)

Low-level API

Constructs drop into an existing CDK application, the stack, naming and log groups follow the application's conventions (scud.SetDefaults).

gateway := scud.NewGateway(stack, jsii.String("Gateway"),
  &scud.GatewayProps{Cors: cloudmcp.Cors("https://example.com")},
)

server := cloudmcp.NewServer(stack, jsii.String("MCP"),
  &cloudmcp.ServerProps{
    FunctionGoProps: &scud.FunctionGoProps{
      SourceCodeModule: "github.com/example/app",
      SourceCodeLambda: "cmd/mcp",
    },
    Route: "/{instance}",
  },
)

server.AllowAccessLambda(gateway.NewAuthorizerLambda(authorizer, nil))
  • Route default is /mcp; POST, GET and DELETE are routed to the function (the function answers 405 to the latter).
  • PayloadFormatVersion default is 2.0, the function accepts both.
  • The function timeout defaults to 29 seconds; synthesis fails if it is 30 seconds or longer (API Gateway HTTP API integration timeout).
  • Access: AllowAccessPublic, AllowAccessApiKey, AllowAccessJWT(api, scopes...), AllowAccessIAM(api, principal), AllowAccessLambda; ServeResourceMetadata for MCP authorization.

Dispatcher

The dispatcher is a single MCP endpoint aggregating tools of worker functions. It lists tools of workers at cold start and forwards tools/call to the owning worker through Lambda Invoke, together with the caller's TokenInfo. Each worker keeps its own IAM role (least privilege per tool). Tool names must be unique across workers.

// worker's main
lambda.Start(serve.Handler(serve.Tool(&mcp.Tool{Name: "sayer"}, sayer.Sayer)))

// CDK
cloudmcp.NewDispatcher(stack, jsii.String("Dispatcher"),
  &cloudmcp.DispatcherProps{
    Name:             "tools",
    MetricsNamespace: "tools",
    Workers:          []awslambda.IFunction{sayer, clock},
  },
).AllowAccessApiKey(gateway.NewAuthorizerBasic("access", "secret"))

The dispatcher function is built from cmd/dispatcher; use package dispatch for your own dispatcher main.

Examples

  • helloworld - MCP server using the high-level API
  • serverless - dispatcher with workers using the low-level API

Both examples are deployable with cdk deploy.

Clients

pkg/auth creates MCP client transports with authentication:

  • auth.NewTransportApiKey access/secret keys as standard Basic credentials
  • auth.NewTransportBearer bearer token (e.g. API keys issued as bearer tokens)
  • auth.NewTransportIAM AWS SigV4 signed requests
transport, err := auth.NewTransportApiKey(auth.ConfigApiKey{Url: "https://...", Access: "access", Secret: "secret"})

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

Authorization header

MCP clients configured by JSON or CLI (VS Code, Claude Code, ...) send the Authorization header as given, build its value for the access method of the server:

  • .AccessApiKey(access, secret): Basic <digest>, where the digest is base64 of access:secret (RFC 7617)
  • .AccessJWT(...), .AccessAwsCognito(...): Bearer <token>, where the token is a JWT issued by your identity provider
  • .AccessPublic(): no header

The digest of Basic credentials:

printf '%s' 'access:secret' | base64
# YWNjZXNzOnNlY3JldA==

Use printf (or echo -n), a trailing newline of plain echo corrupts the digest. GNU base64 wraps output longer than 76 characters, use base64 -w0 on Linux for long keys. Note that Basic credentials are encoded, not encrypted, keep the digest as secret as the keys.

Use in Claude Code

claude mcp add --transport http helloworld https://0000000000.execute-api.eu-west-1.amazonaws.com/mcp \
  --header "Authorization: Basic $(printf '%s' 'access:secret' | base64)"

Use in VS Code

Integration of serverless MCPs is as straightforward as any other, within mcp.json

{
  "servers": {
    "helloworld": {
      "type": "http",
      "url": "https://0000000000.execute-api.eu-west-1.amazonaws.com/mcp",
      "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 server-to-client requests or event streams in Lambda (use server mode)
❌ You're committed to a different cloud provider

Requirements

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

Contributing

cloudmcp 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

See LICENSE

Documentation

Index

Constants

View Source
const DefaultRoute = "/mcp"

DefaultRoute of MCP server

View Source
const MetadataPath = "/.well-known/oauth-protected-resource"

MetadataPath is the well-known path of protected resource metadata.

View Source
const Version = "v0.1.0"

Variables

View Source
var (
	CorsAllowHeaders = []string{
		"Authorization",
		"Content-Type",
		"Accept",
		"Mcp-Session-Id",
		"Mcp-Protocol-Version",
		"Mcp-Method",
		"Mcp-Name",
		"Last-Event-ID",
	}

	CorsExposeHeaders = []string{
		"Mcp-Session-Id",
		"Mcp-Protocol-Version",
		"WWW-Authenticate",
	}
)

Headers of MCP protocol, browser clients send and read them.

View Source
var DefaultTimeout = awscdk.Duration_Seconds(jsii.Number(29))

DefaultTimeout of MCP server function, shorter than the API Gateway HTTP API integration timeout (30 seconds).

Functions

func Cors added in v0.1.0

func Cors(origins ...string) *scud.Cors

Cors returns CORS configuration of the gateway for browser MCP clients (e.g. MCP Inspector), allowing MCP protocol headers.

scud.NewGateway(stack, jsii.String("Gateway"),
	&scud.GatewayProps{Cors: cloudmcp.Cors("https://example.com")},
)

Types

type Dispatcher added in v0.1.0

type Dispatcher struct {
	*Server
	// contains filtered or unexported fields
}

Dispatcher is L3 construct of MCP server, which lists tools of worker functions and forwards tools/call to them through Lambda Invoke. Workers keep their own IAM roles (least privilege per tool), clients connect to the dispatcher's route only. The dispatcher is a Server, grant access to its route with Allow* methods.

func NewDispatcher added in v0.1.0

func NewDispatcher(scope constructs.Construct, id *string, props *DispatcherProps) *Dispatcher

NewDispatcher defines the dispatcher function.

func (*Dispatcher) AddWorker added in v0.1.0

func (d *Dispatcher) AddWorker(worker awslambda.IFunction) *Dispatcher

AddWorker adds the worker function to the dispatcher, granting the dispatcher to invoke it.

type DispatcherProps added in v0.1.0

type DispatcherProps struct {
	// Properties of the dispatcher function (optional).
	// The timeout defaults to 29 seconds, it must be shorter than 30 seconds.
	*awslambda.FunctionProps

	// Implementation name and version reported to clients,
	// default is the construct id and the version of cloudmcp.
	Name, Version string

	// CloudWatch namespace of request metrics (EMF), disabled if empty.
	MetricsNamespace string

	// Route of the dispatcher, default is /mcp.
	Route string

	// Payload format of the integration, default is 2.0.
	PayloadFormatVersion apigw2.PayloadFormatVersion

	// Worker functions running serve.Handler (e.g. serve.Tool).
	// Tool names must be unique across workers.
	Workers []awslambda.IFunction
}

DispatcherProps defines properties of the dispatcher, the single MCP server aggregating tools of worker functions.

type Gateway

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

Gateway is the high-level builder of standalone MCP server deployment: a stack with API Gateway, authorizer and the server function.

cloudmcp.New("cmd/mcp").
	Hostless().
	AccessApiKey("access", "secret").
	Build()

Use NewServer within an existing CDK application instead.

func New

func New(lambda string) *Gateway

New creates the builder for MCP server, whose main package is at the given path relative to the main module (e.g. "cmd/mcp"). The main is written by the project:

func main() {
	lambda.Start(serve.Handler(server.New))
}

func (*Gateway) AccessApiKey

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

AccessApiKey configures API key access, using basic authentication with access and secret keys.

func (*Gateway) AccessAwsCognito

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

AccessAwsCognito configures 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

AccessJWT configures JWT access, using given issuer and optional list of audiences.

func (*Gateway) AccessLambda added in v0.1.0

func (c *Gateway) AccessLambda(lambda string, props *scud.AuthorizerLambdaProps) *Gateway

AccessLambda configures the project's own Lambda authorizer, whose main package is at the given path relative to the module (use package github.com/fogfish/scud/authorizer to implement it).

func (*Gateway) AccessPublic

func (c *Gateway) AccessPublic() *Gateway

AccessPublic configures public access (no authentication).

func (*Gateway) Build

func (c *Gateway) Build()

Build defines and synthesizes the application.

func (*Gateway) Cors added in v0.1.0

func (c *Gateway) Cors(origins ...string) *Gateway

Cors enables CORS for browser MCP clients from the origins, allowing MCP protocol headers.

func (*Gateway) Function added in v0.1.0

func (c *Gateway) Function(props *awslambda.FunctionProps) *Gateway

Function configures properties of the server function (e.g. memory, environment). The timeout must be shorter than 30 seconds.

func (*Gateway) Gateway

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

Gateway configures gateway with custom properties.

func (*Gateway) Host

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

Host configures gateway with custom domain and TLS certificate ARN.

func (*Gateway) Hostless

func (c *Gateway) Hostless() *Gateway

Hostless configures gateway without custom domain, the default API Gateway host is used.

func (*Gateway) Module added in v0.1.0

func (c *Gateway) Module(module string) *Gateway

Module of the server's source code, default is the main module of the CDK application.

func (*Gateway) Name added in v0.1.0

func (c *Gateway) Name(name string) *Gateway

Name of the stack, default is the base name of the server's path. Logs are written to the log group /app/{name}.

func (*Gateway) ResourceMetadata added in v0.1.0

func (c *Gateway) ResourceMetadata() *Gateway

ResourceMetadata routes protected resource metadata (RFC 9728) to the server as public routes. The server enables it with serve.WithResourceServer.

func (*Gateway) Route added in v0.1.0

func (c *Gateway) Route(route string) *Gateway

Route of the server, default is /mcp (see ServerProps.Route).

func (*Gateway) Stack added in v0.1.0

func (c *Gateway) Stack(app awscdk.App) awscdk.Stack

Stack defines the stack of the server within the application.

type Server

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

Server is L3 construct of MCP server as AWS Lambda function.

func NewServer

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

NewServer defines MCP server as Lambda function.

func (*Server) AllowAccessApiKey

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

AllowAccessApiKey grants access to the server via API key authorizer.

func (*Server) AllowAccessIAM

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

AllowAccessIAM grants access to the server via IAM authorizer for the principal.

func (*Server) AllowAccessJWT

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

AllowAccessJWT grants access to the server via JWT (or Cognito) authorizer, requiring the given OAuth scopes.

func (*Server) AllowAccessLambda added in v0.1.0

func (c *Server) AllowAccessLambda(api *scud.AuthorizerLambda) *Server

AllowAccessLambda grants access to the server via the project's own Lambda authorizer (scud.Gateway.NewAuthorizerLambda). The authorizer's context is available to tools at req.Extra.TokenInfo (see serve.DefaultTokenInfo).

func (*Server) AllowAccessPublic

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

AllowAccessPublic grants public access to the server.

func (*Server) ServeResourceMetadata added in v0.1.0

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

ServeResourceMetadata routes the protected resource metadata (RFC 9728) to the server as public routes, see serve.WithResourceServer.

type ServerProps

type ServerProps struct {
	// The function, built from SourceCodeModule/SourceCodeLambda.
	// The timeout defaults to 29 seconds, it must be shorter than 30 seconds.
	// The log group and other defaults follow scud.SetDefaults of the scope.
	*scud.FunctionGoProps

	// Route of the server (e.g. /mcp, /{instance} or /), default is /mcp.
	// The route may contain path parameters, they are available to tools at
	// req.Extra.TokenInfo.Extra["path"].
	Route string

	// Payload format of the integration, default is 2.0.
	// The function accepts both 1.0 and 2.0.
	PayloadFormatVersion apigw2.PayloadFormatVersion
}

ServerProps defines properties of MCP server as Lambda function. The function's main is written by the project:

func main() {
	lambda.Start(serve.Handler(server.New))
}

Directories

Path Synopsis
cmd
dispatcher command
The dispatcher function deployed by cloudmcp.NewDispatcher.
The dispatcher function deployed by cloudmcp.NewDispatcher.
Package dispatch aggregates tools of several worker Lambda functions into one MCP server.
Package dispatch aggregates tools of several worker Lambda functions into one MCP server.
examples
helloworld command
helloworld/lambda command
Lambda function running the MCP server
Lambda function running the MCP server
serverless command
serverless/cmd/clock command
Worker function serving the single tool
Worker function serving the single tool
serverless/cmd/sayer command
Worker function serving the single tool
Worker function serving the single tool
internal
test/authorizer command
Lambda authorizer used by tests of constructs
Lambda authorizer used by tests of constructs
test/server command
MCP server function used by tests of constructs
MCP server function used by tests of constructs
pkg
auth module
Package serve is the runtime of cloudmcp.
Package serve is the runtime of cloudmcp.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL