Cost Explorer MCP Server - Agentcore Runtime Deployment

This directory contains the Cost Explorer MCP Server configured for deployment to Amazon Bedrock Agentcore Runtime with streamable HTTP support on port 8000.

🏗️ Architecture

Original: STDIO-based MCP server for local development
Converted: Streamable HTTP server for Agentcore Runtime deployment
Protocol: MCP (Model Context Protocol)
Transport: Streamable HTTP on port 8000
Deployment: Agentcore Runtime (no Agentcore memory)

📁 Project Structure

cost-explorer-agentcore-deployment/
├── mcp_server.py              # Main MCP server with streamable HTTP
├── requirements.txt           # Python dependencies
├── __init__.py               # Python package marker
├── awslabs/                  # Cost Explorer implementation
│   └── cost_explorer_mcp_server/
├── deploy.py                 # Deployment automation script
├── test_mcp_client.py        # Local testing client
├── test_remote_client.py     # Remote testing client
└── README.md                 # This file

🚀 Quick Start

1. Prerequisites

# Install required tools
pip install bedrock-agentcore-starter-toolkit
pip install mcp[cli]

# Configure AWS credentials
aws configure

2. Test Locally First

# Install dependencies
pip install -r requirements.txt

# Start the MCP server locally
python mcp_server.py

In another terminal:

# Test the local server
python test_mcp_client.py

3. Deploy to Agentcore Runtime

# Run the deployment script
python deploy.py

The script will:

Check prerequisites
Configure the deployment
Deploy to Agentcore Runtime
Save the Agent ARN to agent_arn.txt

4. Test Remote Deployment

# Set environment variables
export AGENT_ARN="your-agent-arn-from-deployment"
export BEARER_TOKEN="your-oauth-token"

# Test the deployed server
python test_remote_client.py

🔧 Manual Deployment Steps

If you prefer manual deployment:

1. Configure Deployment

agentcore configure -e mcp_server.py --protocol MCP

Follow the prompts:

Protocol: MCP
Entry point: mcp_server.py
Authentication: Choose OAuth or Cognito based on your needs

2. Deploy

agentcore launch

🔐 Authentication Setup

Option 1: Cognito User Pool (Recommended)

Create a Cognito User Pool in AWS Console
Configure the user pool for your application
Use the provided credentials during deployment configuration

Option 2: OAuth with Auth0

Set up Auth0 application with Dynamic Client Registration
Configure OAuth settings during deployment
Use Auth0 tokens for authentication

🧪 Testing

Local Testing

# Start server
python mcp_server.py

# Test in another terminal
python test_mcp_client.py

Remote Testing

# Set environment variables
export AGENT_ARN="arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/cost-explorer-xyz123"
export BEARER_TOKEN="your-oauth-token"

# Test deployed server
python test_remote_client.py

🛠️ Available Tools

The Cost Explorer MCP Server provides these tools:

get_today_date - Get current date for relative queries
get_dimension_values - Get available values for dimensions (SERVICE, REGION, etc.)
get_tag_values - Get available tag values
get_cost_and_usage - Retrieve cost and usage data with filtering
get_cost_and_usage_comparisons - Compare costs between periods
get_cost_comparison_drivers - Analyze cost change drivers
get_cost_forecast - Generate cost forecasts

💰 Cost Considerations

Important: Each AWS Cost Explorer API call costs $0.01. The server includes optimizations to minimize API calls, but be aware of potential charges when using the tools extensively.

🔍 Troubleshooting

Local Server Issues

# Check if port 8000 is available
lsof -i :8000

# Check server logs
python mcp_server.py

Deployment Issues

# Check AWS credentials
aws sts get-caller-identity

# Verify agentcore CLI
agentcore --version

# Check deployment status
agentcore status

Remote Connection Issues

Verify BEARER_TOKEN is valid and not expired
Check AGENT_ARN format and encoding
Ensure OAuth/Cognito is properly configured
Verify server deployment status

📚 References

🆘 Support

For issues with:

MCP Server: Check the original cost-explorer-mcp-server documentation
Agentcore Runtime: Refer to AWS Bedrock Agentcore documentation
Authentication: Check your OAuth/Cognito configuration
AWS Costs: Review AWS Cost Explorer API pricing and usage