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)

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

Option 2: OAuth with Auth0

1. Set up Auth0 application with Dynamic Client Registration
2. Configure OAuth settings during deployment
3. 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:

1. get_today_date - Get current date for relative queries
2. get_dimension_values - Get available values for dimensions (SERVICE, REGION, etc.)
3. get_tag_values - Get available tag values
4. get_cost_and_usage - Retrieve cost and usage data with filtering
5. get_cost_and_usage_comparisons - Compare costs between periods
6. get_cost_comparison_drivers - Analyze cost change drivers
7. 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

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

📚 References

• Agentcore Runtime MCP Documentation
• Converting STDIO to Streamable HTTP
• MCP Protocol Documentation
• AWS Cost Explorer API

🆘 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