OpsGuide MCP

A Model Context Protocol (MCP) server that bridges standard MCP clients to the OpsGuide Bedrock AgentCore runtime.

Features

• MCP Protocol: Compatible with standard MCP clients (Claude Desktop, OpenCode, etc.)
• HTTP Bridge: Converts stdio messages to HTTP calls to AgentCore
• Bearer Authentication: JWT token authentication
• Session Management: Handles AgentCore session IDs automatically
• Error Handling: Proper JSON-RPC error responses
• Streaming Support: Handles Server-Sent Events from AgentCore

Installation

npm install -g opsguide-mcp

Or use with npx:

npx opsguide-mcp

Configuration

Environment Variables

Copy .env.example to .env and configure:

# Primary authentication - get from ./get_token.sh
API_KEY=your-bearer-token-here

# Optional: Auto-refresh credentials
[email protected]
COGNITO_PASSWORD=your-password

# Optional: Debug logging
DEBUG=1

Getting Bearer Token

Use the token script with your credentials:

# From the parent directory
./get_token.sh <email> <password>

# Example
./get_token.sh [email protected] 'MyPassword123!'

# For automation (token only)
TOKEN=$(./get_token.sh --token-only [email protected] 'MyPassword123!')
echo "OPSGUIDE_API_KEY=$TOKEN" >> .env

# Or copy manually from verbose output
./get_token.sh [email protected] 'MyPassword123!'
# Copy the Access Token to your .env file
echo 'OPSGUIDE_API_KEY=your-access-token-here' >> .env

Usage

With OpenCode/Claude Code

Add to your MCP client configuration:

{
  "mcpServers": {
    "opsguide": {
      "command": "opsguide-mcp",
      "env": {
        "API_KEY": "your-bearer-token-here"
      }
    }
  }
}

With npx

{
  "mcpServers": {
    "opsguide": {
      "command": "npx",
      "args": ["opsguide-mcp"],
      "env": {
        "API_KEY": "your-bearer-token-here"
      }
    }
  }
}

Direct Command Line

# Run the wrapper
node bin/opsguide-mcp

# With debug logging
DEBUG=1 node bin/opsguide-mcp

# Test with a simple message
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node bin/opsguide-mcp

Architecture

┌─────────────────┐    stdio    ┌─────────────────┐    HTTPS    ┌─────────────────┐
│   MCP Client    │◄──────────►│  MCP Wrapper    │◄──────────►│  AgentCore      │
│ (OpenCode/etc)  │  JSON-RPC   │                 │   Bearer    │   MCP Server    │
└─────────────────┘             └─────────────────┘    Auth     └─────────────────┘

The wrapper:

1. Reads JSON-RPC messages from stdin
2. Authenticates with Bearer tokens
3. Forwards to AgentCore via Streamable HTTP
4. Handles SSE streams and session management
5. Returns responses via stdout

Available Tools

Your AgentCore server exposes these tools:

• add_numbers - Add two numbers together
• multiply_numbers - Multiply two numbers together
• greet_user - Greet a user by name using JWT token
• get_current_user - Get current user information from JWT token
• query_user_data - Example database query with user context

Authentication Flow

1. Environment Token: Uses OPSGUIDE_API_KEY if available
2. Cached Token: Uses cached token if still valid
3. Auto Refresh: Uses Cognito credentials to refresh expired tokens
4. Token Validation: Automatically handles token expiry

Debugging

Enable debug logging:

DEBUG=1 node bin/opsguide-mcp
# or
OPSGUIDE_DEBUG=1 node bin/opsguide-mcp

Debug output goes to stderr, so it won't interfere with the JSON-RPC protocol on stdout.

Error Handling

The wrapper handles several error scenarios:

• Authentication Failures: Token expired or invalid
• Network Errors: Connection issues to AgentCore
• HTTP Errors: AgentCore server errors
• Protocol Errors: Invalid JSON-RPC messages
• Session Errors: Session expiry and renewal

Configuration Details

AgentCore Connection

• Endpoint: https://bedrock-agentcore.us-east-1.amazonaws.com
• Agent ARN: arn:aws:bedrock-agentcore:us-east-1:654654574429:runtime/opsguide_mcp_server_example-feNooQ7JbB
• Qualifier: DEFAULT
• Transport: Streamable HTTP with SSE support

Authentication

• Type: Bearer token (AWS Cognito JWT)
• Header: Authorization: Bearer <token>
• Refresh: Automatic via AWS CLI and Cognito
• Session: Managed via Mcp-Session-Id headers

Troubleshooting

Token Issues

# Get new token
./get_token.sh <email> <password>

# Update environment with new token
TOKEN=$(./get_token.sh --token-only <email> <password>)
echo "OPSGUIDE_API_KEY=$TOKEN" > .env

Connection Issues

# Test AgentCore status
agentcore status

# Check wrapper with debug
DEBUG=1 node bin/opsguide-mcp

JSON-RPC Issues

# Test with curl (should fail - shows HTTP vs stdio difference)
curl -X POST https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/...

# Test wrapper directly
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | DEBUG=1 node bin/opsguide-mcp

License

MIT