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

``bash
npm install -g opsguide-mcp
`

Or use with npx:

`bash
npx opsguide-mcp
`

Configuration

$3

Copy .env.example to .env and configure:

`bash


Primary authentication - get from ./get_token.sh

API_KEY=your-bearer-token-here

Optional: Auto-refresh credentials

COGNITO_USERNAME=me@ekky.dev
COGNITO_PASSWORD=your-password

Optional: Debug logging

DEBUG=1
`

$3

Use the token script with your credentials:

`bash


From the parent directory

./get_token.sh

Example

./get_token.sh me@example.com 'MyPassword123!'

For automation (token only)

TOKEN=$(./get_token.sh --token-only me@example.com 'MyPassword123!')
echo "OPSGUIDE_API_KEY=$TOKEN" >> .env

Or copy manually from verbose output

./get_token.sh me@example.com 'MyPassword123!'

Copy the Access Token to your .env file

echo 'OPSGUIDE_API_KEY=your-access-token-here' >> .env
`

Usage

$3

Add to your MCP client configuration:

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

$3

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

$3

`bash


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:

`bash
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

$3

- 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

$3

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

Troubleshooting

$3

`bash


Get new token

./get_token.sh

Update environment with new token

TOKEN=$(./get_token.sh --token-only )
echo "OPSGUIDE_API_KEY=$TOKEN" > .env
`

$3

`bash


Test AgentCore status

agentcore status

Check wrapper with debug

DEBUG=1 node bin/opsguide-mcp
`

$3

`bash


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