
Connecting the AWS MCP Server to AWS DevOps Agent
AWS DevOps Agent can be extended with external tools via the Model Context Protocol (MCP). This guide walks through exactly how we connected the AWS Billing and Cost Management MCP server to a DevOps Agent, including all the infrastructure code, IAM permissions, and the gotchas we hit along the way.
AWS DevOps Agent can be extended with external tools via the Model Context Protocol (MCP). This guide walks through exactly how we connected the AWS Billing and Cost Management MCP server to a DevOps Agent, including all the infrastructure code, IAM permissions, and the gotchas we hit along the way.
What we built
The
awslabs Billing and Cost Management MCP server is normally run locally via uvx . To connect it to DevOps Agent it needs to be reachable as a public HTTPS endpoint implementing the Streamable HTTP transport protocol. We solved this with a Lambda function behind an API Gateway HTTP API — no containers, no external dependencies, just Python and boto3.The end result: DevOps Agent can now answer questions like "what's driving my cost increase this month?" or "are there any cost anomalies?" during incident investigations.
Architecture
DevOps Agent | | HTTPS POST /mcp (JSON-RPC 2.0) | x-api-key header vAPI Gateway HTTP API (v2) | | Lambda authorizer validates x-api-key against Secrets Manager vMCP Server Lambda (Python 3.13, arm64) | | boto3 vCost Explorer / Budgets / Cost Optimization Hub / Compute OptimizerTwo Lambda functions:
MCP server — handles the MCP protocol (initialize, tools/list, tools/call) and dispatches to billing APIs
Authorizer — validates the API key from Secrets Manager on every request
PLEASE NOTE THIS CODE WAS GENERATED BY KIRO AND SO SHOULD BE TESTED TO FOLLOW YOUR SECURITY PROTOCOLS. THIS IS EXAMPLE CODE
Prerequisites
- AWS account with Cost Explorer enabled (on by default, but must have billing data)
- AWS DevOps Agent with an Agent Space already created
- AWS CLI configured
The CloudFormation template
All of the resource definitions in the sections below belong in a single CloudFormation template file —
billing-mcp-server.yaml . Each section is a logical group of resources that you add to the same Resources: block. The complete assembled template is shown at the end of this guide, followed by the deploy command.Here is the full structure of what the template contains:
billing-mcp-server.yaml├── Parameters│ └── Environment (naming prefix, default: demo)├── Resources│ ├── McpLambdaLogGroup (CloudWatch log group for MCP server)│ ├── AuthorizerLogGroup (CloudWatch log group for authorizer)│ ├── McpApiKeySecret (Secrets Manager — auto-generated API key)│ ├── McpLambdaRole (IAM role — read-only billing permissions)│ ├── AuthorizerRole (IAM role — Secrets Manager read only)│ ├── McpLambdaFunction (MCP protocol + billing tool implementations)│ ├── AuthorizerFunction (validates x-api-key header)│ ├── McpHttpApi (API Gateway HTTP API v2)│ ├── McpLambdaIntegration (Lambda proxy integration)│ ├── McpAuthorizer (REQUEST authorizer)│ ├── McpApiPostRoute (POST /mcp)│ ├── McpApiGetRoute (GET /mcp)│ ├── McpApiStage ($default stage, auto-deploy)│ ├── McpLambdaApiPermission (allow API GW to invoke MCP Lambda)│ └── AuthorizerLambdaPermission (allow API GW to invoke authorizer)└── Outputs ├── McpEndpointUrl (the URL you paste into DevOps Agent) ├── ApiKeySecretArn (ARN to retrieve the API key from) └── LambdaFunctionName
Building the template piece by piece
1. Parameters
At the very top of
billing-mcp-server.yaml , before Resources: :AWSTemplateFormatVersion: '2010-09-09'Description: > Hosts a Billing and Cost Management MCP server as a Streamable HTTP endpoint via Lambda + API Gateway HTTP API, suitable for registration as a DevOps Agent Capability Provider.
Parameters: Environment: Type: String Default: demo Description: Environment name used for resource naming and tagging
2. CloudWatch log groups
Add these to
Resources: . Always pre-create log groups so you control retention — if you let Lambda create them automatically they default to never-expire. McpLambdaLogGroup: Type: AWS::Logs::LogGroup DeletionPolicy: Retain UpdateReplacePolicy: Retain Properties: LogGroupName: !Sub '/aws/lambda/${Environment}-billing-mcp-server' RetentionInDays: 7 Tags: - Key: FinOps Value: billing-mcp-server
AuthorizerLogGroup: Type: AWS::Logs::LogGroup DeletionPolicy: Retain UpdateReplacePolicy: Retain Properties: LogGroupName: !Sub '/aws/lambda/${Environment}-billing-mcp-authorizer' RetentionInDays: 7 Tags: - Key: FinOps Value: billing-mcp-server
3. API key secret
Rather than hardcoding a secret, CloudFormation generates a 32-character key at deploy time and stores it in Secrets Manager. Add to
Resources: : McpApiKeySecret: Type: AWS::SecretsManager::Secret DeletionPolicy: Retain UpdateReplacePolicy: Retain Properties: Name: !Sub '/${Environment}/billing-mcp-server/api-key' Description: API key for DevOps Agent to authenticate with the billing MCP server GenerateSecretString: SecretStringTemplate: '{}' GenerateStringKey: api_key PasswordLength: 32 ExcludeCharacters: '"@/\' Tags: - Key: FinOps Value: billing-mcp-server
4. IAM roles
Two roles — one for each Lambda. Add both to
Resources: .MCP server role — read-only access to billing APIs. Keep it scoped to exactly these actions:
McpLambdaRole: Type: AWS::IAM::Role Properties: RoleName: !Sub '${Environment}-billing-mcp-lambda-role' AssumeRolePolicyDocument: Version: '2012-10-17' Statement: - Effect: Allow Principal: Service: lambda.amazonaws.com Action: sts:AssumeRole ManagedPolicyArns: - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole Policies: - PolicyName: BillingMcpReadOnly PolicyDocument: Version: '2012-10-17' Statement: - Sid: CostExplorer Effect: Allow Action: - ce:GetCostAndUsage - ce:GetCostAndUsageWithResources - ce:GetCostForecast - ce:GetUsageForecast - ce:GetDimensionValues - ce:GetTags - ce:GetCostCategories - ce:GetAnomalies - ce:GetReservationCoverage - ce:GetReservationUtilization - ce:GetSavingsPlansCoverage - ce:GetSavingsPlansUtilization - ce:GetSavingsPlansUtilizationDetails - ce:GetCostAndUsageComparisons - ce:GetCostComparisonDrivers - ce:ListCostAllocationTags - ce:ListCostAllocationTagBackfillHistory - ce:DescribeCostCategoryDefinition - ce:ListCostCategoryDefinitions Resource: '*' - Sid: Budgets Effect: Allow Action: - budgets:ViewBudget Resource: !Sub 'arn:aws:budgets::${AWS::AccountId}:budget/*' - Sid: FreeTier Effect: Allow Action: - freetier:GetFreeTierUsage Resource: '*' - Sid: Pricing Effect: Allow Action: - pricing:DescribeServices - pricing:GetAttributeValues - pricing:GetProducts Resource: '*' - Sid: CostOptimizationHub Effect: Allow Action: - cost-optimization-hub:GetRecommendation - cost-optimization-hub:ListRecommendations - cost-optimization-hub:ListRecommendationSummaries Resource: '*' - Sid: ComputeOptimizer Effect: Allow Action: - compute-optimizer:GetAutoScalingGroupRecommendations - compute-optimizer:GetEBSVolumeRecommendations - compute-optimizer:GetEC2InstanceRecommendations - compute-optimizer:GetECSServiceRecommendations - compute-optimizer:GetRDSDatabaseRecommendations - compute-optimizer:GetLambdaFunctionRecommendations - compute-optimizer:GetIdleRecommendations - compute-optimizer:GetEnrollmentStatus Resource: '*' - Sid: PricingCalculator Effect: Allow Action: - bcm-pricing-calculator:GetPreferences - bcm-pricing-calculator:GetWorkloadEstimate - bcm-pricing-calculator:ListWorkloadEstimateUsage - bcm-pricing-calculator:ListWorkloadEstimates Resource: '*' Tags: - Key: FinOps Value: billing-mcp-serverAuthorizer role — only needs to read the one secret:
AuthorizerRole: Type: AWS::IAM::Role Properties: RoleName: !Sub '${Environment}-billing-mcp-authorizer-role' AssumeRolePolicyDocument: Version: '2012-10-17' Statement: - Effect: Allow Principal: Service: lambda.amazonaws.com Action: sts:AssumeRole ManagedPolicyArns: - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole Policies: - PolicyName: ReadApiKeySecret PolicyDocument: Version: '2012-10-17' Statement: - Effect: Allow Action: - secretsmanager:GetSecretValue Resource: !Ref McpApiKeySecret Tags: - Key: FinOps Value: billing-mcp-server
5. MCP server Lambda
This is the core of the solution. The Lambda implements the MCP Streamable HTTP protocol directly using only Python stdlib and boto3 — no external packages, no container image needed.
It handles four JSON-RPC methods that DevOps Agent calls:
Method | Purpose |
|---|---|
ping | Health check — DevOps Agent calls this to verify the server is alive |
initialize | Returns server name, version, and capabilities |
tools/list | Returns the full tool manifest with input schemas |
tools/call | Dispatches to the appropriate boto3 billing API call |
It also handles
GET /mcp — DevOps Agent probes this route on connection to check for SSE support.The Lambda entry point (Python, inside the
ZipFile block):def lambda_handler(event, context): method = event.get('requestContext', {}).get('http', {}).get('method', 'POST')
# GET /mcp — SSE probe, return 200 with event-stream headers if method == 'GET': return { 'statusCode': 200, 'headers': {'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache'}, 'body': '', }
# POST /mcp — JSON-RPC 2.0 request body = event.get('body', '{}') or '{}' if event.get('isBase64Encoded'): import base64 body = base64.b64decode(body).decode('utf-8')
response = handle_jsonrpc(body) return { 'statusCode': 200, 'headers': {'Content-Type': 'application/json'}, 'body': json.dumps(response), }Each tool is defined with a name, description, and JSON Schema. The name matters — see gotcha 1 about the 64-character limit:
TOOLS = [ { "name": "get_cost_and_usage", "description": "Retrieve AWS cost and usage data for a time period.", "inputSchema": { "type": "object", "properties": { "start_date": {"type": "string", "description": "Start date YYYY-MM-DD (inclusive)"}, "end_date": {"type": "string", "description": "End date YYYY-MM-DD (exclusive)"}, "granularity": {"type": "string", "enum": ["DAILY", "MONTHLY"]}, "group_by_dimension": {"type": "string", "description": "e.g. SERVICE, REGION"} }, "required": ["start_date", "end_date"] } }, # get_cost_forecast, get_cost_anomalies, describe_budgets, list_cost_optimizations # See the complete template at the end of this guide]The CloudFormation resource — note
arm64 architecture and DependsOn the log group: McpLambdaFunction: Type: AWS::Lambda::Function DependsOn: McpLambdaLogGroup Properties: FunctionName: !Sub '${Environment}-billing-mcp-server' Runtime: python3.13 Handler: index.lambda_handler Role: !GetAtt McpLambdaRole.Arn Timeout: 60 MemorySize: 512 Architectures: - arm64 Environment: Variables: ENVIRONMENT: !Ref Environment Code: ZipFile: | # Full Python implementation — see complete template at end of guide Tags: - Key: FinOps Value: billing-mcp-server
6. Authorizer Lambda
Validates the
x-api-key header on every request. The key is cached in memory after the first Secrets Manager call to avoid per-request latency:_cached_key = None
def get_api_key(): global _cached_key if _cached_key: return _cached_key resp = sm.get_secret_value(SecretId=SECRET_ARN) _cached_key = json.loads(resp['SecretString'])['api_key'] return _cached_key
def lambda_handler(event, context): token = (event.get('headers') or {}).get('x-api-key', '') valid = token == get_api_key() return { 'isAuthorized': valid, 'context': {'authorized': str(valid)}, }The CloudFormation resource:
AuthorizerFunction: Type: AWS::Lambda::Function DependsOn: AuthorizerLogGroup Properties: FunctionName: !Sub '${Environment}-billing-mcp-authorizer' Runtime: python3.13 Handler: index.lambda_handler Role: !GetAtt AuthorizerRole.Arn Timeout: 10 MemorySize: 128 Architectures: - arm64 Environment: Variables: SECRET_ARN: !Ref McpApiKeySecret Code: ZipFile: | # Full Python implementation — see complete template at end of guide Tags: - Key: FinOps Value: billing-mcp-server
7. API Gateway HTTP API
Use HTTP API (v2), not REST API (v1). DevOps Agent requires Streamable HTTP transport which depends on payload format 2.0, only available in HTTP API.
McpHttpApi: Type: AWS::ApiGatewayV2::Api Properties: Name: !Sub '${Environment}-billing-mcp-api' ProtocolType: HTTP Description: Streamable HTTP endpoint for the Billing MCP server
McpLambdaIntegration: Type: AWS::ApiGatewayV2::Integration Properties: ApiId: !Ref McpHttpApi IntegrationType: AWS_PROXY IntegrationUri: !GetAtt McpLambdaFunction.Arn PayloadFormatVersion: '2.0' TimeoutInMillis: 29000
McpAuthorizer: Type: AWS::ApiGatewayV2::Authorizer Properties: ApiId: !Ref McpHttpApi AuthorizerType: REQUEST AuthorizerUri: !Sub 'arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${AuthorizerFunction.Arn}/invocations' AuthorizerPayloadFormatVersion: '2.0' EnableSimpleResponses: true Name: ApiKeyAuthorizer IdentitySource: - '$request.header.x-api-key'
McpApiPostRoute: Type: AWS::ApiGatewayV2::Route Properties: ApiId: !Ref McpHttpApi RouteKey: 'POST /mcp' AuthorizationType: CUSTOM AuthorizerId: !Ref McpAuthorizer Target: !Sub 'integrations/${McpLambdaIntegration}'
McpApiGetRoute: Type: AWS::ApiGatewayV2::Route Properties: ApiId: !Ref McpHttpApi RouteKey: 'GET /mcp' AuthorizationType: CUSTOM AuthorizerId: !Ref McpAuthorizer Target: !Sub 'integrations/${McpLambdaIntegration}'
McpApiStage: Type: AWS::ApiGatewayV2::Stage Properties: ApiId: !Ref McpHttpApi StageName: '$default' AutoDeploy: true
McpLambdaApiPermission: Type: AWS::Lambda::Permission Properties: FunctionName: !Ref McpLambdaFunction Action: lambda:InvokeFunction Principal: apigateway.amazonaws.com SourceArn: !Sub 'arn:aws:execute-api:${AWS::Region}:${AWS::AccountId}:${McpHttpApi}/*/*'
AuthorizerLambdaPermission: Type: AWS::Lambda::Permission Properties: FunctionName: !Ref AuthorizerFunction Action: lambda:InvokeFunction Principal: apigateway.amazonaws.com SourceArn: !Sub 'arn:aws:execute-api:${AWS::Region}:${AWS::AccountId}:${McpHttpApi}/*'
8. Outputs
Outputs: McpEndpointUrl: Description: Paste this URL into DevOps Agent Capability Providers. Auth header: x-api-key Value: !Sub 'https://${McpHttpApi}.execute-api.${AWS::Region}.amazonaws.com/mcp' Export: Name: !Sub '${AWS::StackName}-McpEndpointUrl'
ApiKeySecretArn: Description: Retrieve the API key value from this secret (field: api_key) Value: !Ref McpApiKeySecret Export: Name: !Sub '${AWS::StackName}-ApiKeySecretArn'
LambdaFunctionName: Value: !Ref McpLambdaFunction Export: Name: !Sub '${AWS::StackName}-LambdaName'
Gotchas
1. The MCP server name affects tool name length
DevOps Agent enforces a 64 character limit on the combined identifier
{server_name}_{tool_name} . The tool list_cost_optimization_recommendations is 38 characters. If you name the server billing-cost-management-mcp-server (30 chars), the combined name is 69 characters — over the limit and DevOps Agent will reject it.The fix: use a short server name like
bcm . We also shortened the tool name to list_cost_optimizations .Always check before registering:
len(server_name) + 1 + len(longest_tool_name) <= 642. Use HTTP API (v2), not REST API (v1)
DevOps Agent requires the Streamable HTTP transport protocol. This only works with API Gateway HTTP API (v2) using
PayloadFormatVersion: '2.0' . REST API (v1) does not support this and will cause connection failures.3. AuthorizerFunctionArn vs AuthorizerUri
For
AWS::ApiGatewayV2::Authorizer , the Lambda is specified via AuthorizerUri using the full invocation ARN format — not AuthorizerFunctionArn . That property belongs to REST API (v1) authorizers. Using the wrong one causes an AWS::EarlyValidation::PropertyValidation failure with the message "Unsupported property [AuthorizerFunctionArn]".Correct form:
AuthorizerUri: !Sub 'arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${AuthorizerFunction.Arn}/invocations'4. API Gateway v2 Tags reject intrinsic functions
AWS::ApiGatewayV2::Api and AWS::ApiGatewayV2::Stage use a flat key-value map for tags, unlike most other resources which use a list. This means !Ref and !Sub cannot be used as tag values — CloudFormation treats them as literal strings and rejects the template with "Tag [Key] contained invalid characters". Use plain string values or omit tags on these two resource types.5. TimeoutInMillis maximum is 29000
API Gateway HTTP API has a hard maximum integration timeout of 30 seconds. Setting
TimeoutInMillis: 60000 causes an early validation failure. Use 29000 .6. AWS::EarlyValidation errors are hard to debug
When CloudFormation's early validation hook fires, the changeset fails before any resources are created, so
describe-stack-events shows nothing useful. Get the detail from the changeset directly:CHANGESET=$(aws cloudformation list-change-sets \ --stack-name billing-mcp-server-stack \ --query 'Summaries[0].ChangeSetName' \ --output text)
aws cloudformation describe-change-set \ --stack-name billing-mcp-server-stack \ --change-set-name $CHANGESET \ --query '{Status: Status, StatusReason: StatusReason}'Run
cfn-lint locally before deploying to catch these earlier:pip install cfn-lintcfn-lint billing-mcp-server.yaml7. Do not use !Ref AWS::AccountId in Lambda environment variables
Passing
!Ref AWS::AccountId as a Lambda environment variable value can trigger early validation failures in some accounts. If you need the account ID at runtime, call STS from within the Lambda:account_id = boto3.client('sts').get_caller_identity()['Account']8. The awslabs billing MCP server has no public ECR image
The
awslabs.billing-cost-management-mcp-server package is distributed via uvx (a Python package), not as a container image. There is no public.ecr.aws/awslabs/billing-cost-management-mcp-server image. Attempting to use a container-based Lambda with that URI fails at changeset creation because CloudFormation validates image URIs before creating any resources. The solution used in this guide is to implement the MCP protocol directly in a zip-based Lambda using boto3.
Deploy
Once you have assembled all the sections above into
billing-mcp-server.yaml , deploy with:aws cloudformation deploy \ --stack-name billing-mcp-server-stack \ --template-file billing-mcp-server.yaml \ --capabilities CAPABILITY_NAMED_IAM \ --tags Key=FinOps,Value=billing-mcp-serverThen retrieve the two values you need for the DevOps Agent console:
# Endpoint URLaws cloudformation describe-stacks \ --stack-name billing-mcp-server-stack \ --query "Stacks[0].Outputs[?OutputKey=='McpEndpointUrl'].OutputValue" \ --output text
# API keySECRET_ARN=$(aws cloudformation describe-stacks \ --stack-name billing-mcp-server-stack \ --query "Stacks[0].Outputs[?OutputKey=='ApiKeySecretArn'].OutputValue" \ --output text)
aws secretsmanager get-secret-value \ --secret-id "$SECRET_ARN" \ --query SecretString \ --output text | python3 -c "import sys,json; print(json.load(sys.stdin)['api_key'])"
Register in DevOps Agent console
MCP servers are registered at the account level first, then added to individual Agent Spaces.
Account-level registration:
- AWS Console -> DevOps Agent -> Capability Providers (left nav)
- Find MCP Server in the Available section -> click Register
- Fill in:
- Name:
bcm(keep it short — see gotcha 1)
- Endpoint URL: the URL from the stack output
- Description: Billing and Cost Management read-only tools
- Next -> select API Key
- Fill in:
- API key name:
billing-mcp-key
- Header name:
x-api-key
- API key value: the key retrieved from Secrets Manager
- Submit — DevOps Agent probes the endpoint to validate the connection
Add to your Agent Space:
- Select your Agent Space -> Capabilities tab -> MCP Servers -> Add
- Select
bcm
- Choose Select specific tools and enable only what you need:
-
get_cost_and_usage
-
get_cost_forecast
-
get_cost_anomalies
-
describe_budgets
-
list_cost_optimizations
Only allowlist read-only tools. Never expose tools that can modify or delete resources.
Verifying the connection
Check the Lambda logs to confirm DevOps Agent is connecting successfully:
aws logs tail /aws/lambda/demo-billing-mcp-server --followYou should see
initialize and tools/list calls when DevOps Agent validates the connection. A successful initialize response looks like:{ "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2024-11-05", "capabilities": {"tools": {}}, "serverInfo": { "name": "billing-cost-management-mcp-server", "version": "1.0.0" } }}
Cost
Resource | Cost |
|---|---|
Lambda (512 MB, arm64) | Effectively free at low invocation rates |
API Gateway HTTP API | $1.00 per million requests |
Secrets Manager | $0.40/secret/month |
CloudWatch Logs | $0.50/GB ingested |
The billing API calls themselves (Cost Explorer, Budgets) are free for read operations within normal usage limits.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article