Opsguide workflow builder MCP
npm install opsguide-mcp-1A Model Context Protocol (MCP) server that bridges standard MCP clients to the OpsGuide Bedrock AgentCore runtime.
- 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
``bash`
npm install -g opsguide-mcp
Or use with npx:
`bash`
npx opsguide-mcp
Copy .env.example to .env and configure:
`bashPrimary authentication - get from ./get_token.sh
API_KEY=your-bearer-token-here
$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" >> .envOr 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-mcpWith debug logging
DEBUG=1 node bin/opsguide-mcpTest 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 contextAuthentication 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 expiryDebugging
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 headersTroubleshooting
$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 statusCheck 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
``MIT