OpsGuide MCP Proxy

A stateless Model Context Protocol (MCP) server proxy for OpsGuide's Amazon Bedrock AgentCore Runtime. This proxy creates fresh connections for each request, ensuring no sessions are maintained.

Overview

This stateless proxy server acts as a bridge between:

• MCP clients (like Claude Desktop, Cursor) that communicate via stdio
• Amazon Bedrock AgentCore Runtime that hosts your MCP server via HTTP

Claude Desktop ↔ opsguide-mcp (stateless proxy) ↔ Fresh HTTP Connection ↔ Bedrock AgentCore ↔ Your Tools

Key Features

• ✅ Stateless Design: No persistent connections or sessions
• ✅ Fresh Connections: Each request creates a new connection to Bedrock
• ✅ Tool Proxying: Forwards list_tools and call_tool requests
• ✅ Simple Configuration: Only requires API_KEY

Features

• Protocol Bridge: Converts between stdio (MCP client) and HTTP (Bedrock AgentCore)
• Tool Proxying: Forwards all tool calls to your Bedrock-hosted MCP server
• Resource Access: Proxies resource reading and listing
• Prompt Support: Forwards prompt operations
• uvx Compatible: Easy installation and usage with uvx
• Environment Configuration: Uses standard environment variables

Prerequisites

• Python 3.10 or higher
• uv package manager
• Amazon Bedrock AgentCore Runtime with deployed MCP server
• Valid API key and agent ARN

Installation

For Claude Code

Add this configuration to your Claude Code MCP settings:

{
  "mcpServers": {
    "opsguide-mcp": {
      "command": "uvx",
      "args": ["opsguide-mcp@latest"],
      "env": {
        "API_KEY": "your-bearer-token"
      }
    }
  }
}

Direct Installation

# Install with uvx (recommended)
uvx opsguide-mcp

# Or install with pip
pip install opsguide-mcp

Environment Variables

Only one environment variable is required:

• API_KEY: The bearer token for authentication

Hardcoded Configuration:

• AGENT_ARN: arn:aws:bedrock-agentcore:us-east-1:654654574429:runtime/opsguide_mcp_server_example-feNooQ7JbB
• AWS_REGION: us-east-1

Example .env file

API_KEY=eyJraWQiOiI3RG1ZaXlQbnpoUXR6cmRXNmtvWEd5anhaZU9FaitXcHBpck1rcDlvbHFjPSIsImFsZyI6IlJTMjU2In0...

Usage

With Claude Code

1. Configure the MCP server in Claude Code settings (see installation section)
2. Restart Claude Code
3. Your Bedrock-hosted MCP tools will be available in Claude Code

Command Line

# Run directly
opsguide-mcp

# Run with uvx
uvx opsguide-mcp

# Run with environment variable
API_KEY="your-bearer-token" opsguide-mcp

How It Works

1. Startup: The proxy server reads your environment variables
2. Connection: Establishes HTTP connection to Bedrock AgentCore Runtime
3. Discovery: Lists available tools, resources, and prompts from your MCP server
4. Proxying: Forwards all MCP requests from Claude Code to Bedrock AgentCore
5. Response: Returns results back to Claude Code via stdio

Troubleshooting

Common Issues

Connection Failed

• Verify your API_KEY is correct and not expired
• Check that your Bedrock AgentCore runtime is running
• Ensure you have network access to bedrock-agentcore.us-east-1.amazonaws.com

No Tools Available

• Check that your MCP server is properly deployed in Bedrock AgentCore
• Verify the runtime is in "DEFAULT" qualifier state
• Check logs for connection errors

Authentication Errors

• Ensure your API_KEY (bearer token) is valid and not expired
• Verify the token has permission to invoke the specified runtime

Debug Mode

Run with debug logging:

PYTHONPATH=. python -m bedrock_mcp_proxy.server

Development

Local Development

# Clone the repository
git clone https://github.com/your-username/opsguide-mcp
cd opsguide-mcp

# Install dependencies
uv sync

# Run locally
uv run opsguide-mcp

Testing

# Test the connection
python test_connection.py

Security Considerations

• API Keys: Store API keys securely using environment variables or secure credential management
• Network Access: The proxy requires outbound HTTPS access to AWS Bedrock AgentCore
• Authentication: Bearer tokens should be rotated regularly
• Logging: Be careful not to log sensitive information

License

MIT License - see LICENSE file for details.

Support

For issues related to:

• This proxy: Open an issue on this repository
• Bedrock AgentCore: Consult AWS documentation
• Claude Code: Check Claude Code documentation