AWS Builder Center
Connecting the AWS MCP Server to AWS DevOps Agent

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
v
API Gateway HTTP API (v2)
|
| Lambda authorizer validates x-api-key against Secrets Manager
v
MCP Server Lambda (Python 3.13, arm64)
|
| boto3
v
Cost Explorer / Budgets / Cost Optimization Hub / Compute Optimizer
Two 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-server
Authorizer 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) <= 64

2. 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-lint
cfn-lint billing-mcp-server.yaml

7. 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-server
Then retrieve the two values you need for the DevOps Agent console:
# Endpoint URL
aws cloudformation describe-stacks \
--stack-name billing-mcp-server-stack \
--query "Stacks[0].Outputs[?OutputKey=='McpEndpointUrl'].OutputValue" \
--output text

# API key
SECRET_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:
  1. AWS Console -> DevOps Agent -> Capability Providers (left nav)
  1. Find MCP Server in the Available section -> click Register
  1. 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
  1. Next -> select API Key
  1. Fill in:
  • API key name:  billing-mcp-key 
  • Header name:  x-api-key 
  • API key value: the key retrieved from Secrets Manager
  1. Submit — DevOps Agent probes the endpoint to validate the connection
Add to your Agent Space:
  1. Select your Agent Space -> Capabilities tab -> MCP Servers -> Add
  1. Select  bcm 
  1. 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 --follow
You 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.
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article