cognito-mcp-proxy 0.1.0

Cognito OAuth stdio proxy for AWS Bedrock AgentCore Runtimes

cognito-mcp-proxy

Cognito OAuth stdio proxy for AWS Bedrock AgentCore Runtimes

A lightweight, uvx-installable package that bridges MCP clients (Kiro IDE, Claude Desktop) with AgentCore Runtimes secured by Cognito/EntraID OAuth. No .env files, no AWS CLI needed.

Architecture

Kiro IDE <--stdio (JSON-RPC)--> cognito-mcp-proxy <--HTTPS + Bearer JWT--> AgentCore Runtime
                                       |
                                 Cognito OAuth PKCE
                                 (browser sign-in)

How It Works

1. On startup, opens your browser for Cognito/EntraID sign-in (OAuth PKCE)
2. After auth, reads JSON-RPC messages from stdin (from Kiro)
3. For each request: refreshes the JWT, sends it as Bearer token to the AgentCore runtime
4. Parses the SSE/JSON response and writes JSON-RPC back to stdout

Installation & Usage

Option 1: uvx (Recommended)

Add to your MCP config (~/.kiro/settings/mcp.json or .kiro/settings/mcp.json):

{
  "mcpServers": {
    "redshift-secure": {
      "command": "uvx",
      "args": ["cognito-mcp-proxy@latest"],
      "env": {
        "AGENTCORE_REGION": "us-east-1",
        "AGENTCORE_RUNTIME_ID": "arn:aws:bedrock-agentcore:us-east-1:123456789:runtime/YourRuntime-AbcXyz",
        "COGNITO_DOMAIN": "https://your-pool.auth.us-east-1.amazoncognito.com",
        "COGNITO_CLIENT_ID": "your_cognito_client_id"
      },
      "disabled": false,
      "autoApprove": ["whoami"]
    }
  }
}

Option 2: Direct Python (Fallback)

{
  "mcpServers": {
    "redshift-secure": {
      "command": "python",
      "args": ["-m", "cognito_mcp_proxy"],
      "env": {
        "AGENTCORE_REGION": "us-east-1",
        "AGENTCORE_RUNTIME_ID": "arn:aws:bedrock-agentcore:...",
        "COGNITO_DOMAIN": "https://...",
        "COGNITO_CLIENT_ID": "..."
      },
      "disabled": false
    }
  }
}

Environment Variables

All configuration is via environment variables set in the env block of your mcp.json:

AgentCore Runtime (Option A — recommended: components)

Variable	Required	Default	Description
AGENTCORE_REGION	Yes*	Extracted from ARN	AWS region (e.g., us-east-1)
AGENTCORE_RUNTIME_ID	Yes*	—	Runtime ARN (e.g., arn:aws:bedrock-agentcore:us-east-1:123456:runtime/MyRuntime-Abc)
AGENTCORE_QUALIFIER	No	DEFAULT	Runtime qualifier/alias

AgentCore Runtime (Option B — advanced: full URL)

Variable	Required	Default	Description
AGENTCORE_RUNTIME_URL	Yes*	—	Full invocation URL (overrides region/ID/qualifier)

*One of Option A or Option B must be provided.

The proxy builds the URL as:

https://bedrock-agentcore.{REGION}.amazonaws.com/runtimes/{URL_ENCODED_ARN}/invocations?qualifier={QUALIFIER}

Cognito OAuth

Variable	Required	Default	Description
COGNITO_DOMAIN	Yes	—	Cognito User Pool domain (with or without https://)
COGNITO_CLIENT_ID	Yes	—	Cognito App Client ID
COGNITO_REDIRECT_URI	No	http://localhost:22553/oauth/callback	OAuth callback URI
COGNITO_SCOPE	No	openid email	OAuth scopes
COGNITO_CALLBACK_PORT	No	22553	Local port for OAuth callback server
COGNITO_REQUEST_TIMEOUT	No	120	HTTP timeout in seconds for runtime calls

First-Time Setup

1. Add the MCP configuration to your mcp.json (see above)
2. Restart Kiro (or reconnect MCP servers)
3. On first request, your browser opens for Cognito/Microsoft sign-in
4. Complete sign-in — you'll see "Authentication complete"
5. Return to Kiro and test: ask "run whoami using redshift-secure"

Connecting to Different Runtimes

Since all config is via env vars, you can have multiple entries pointing to different runtimes:

{
  "mcpServers": {
    "redshift-secure": {
      "command": "uvx",
      "args": ["cognito-mcp-proxy@latest"],
      "env": {
        "AGENTCORE_REGION": "us-east-1",
        "AGENTCORE_RUNTIME_ID": "arn:aws:bedrock-agentcore:us-east-1:123456:runtime/Redshift-Prod",
        "COGNITO_DOMAIN": "https://my-pool.auth.us-east-1.amazoncognito.com",
        "COGNITO_CLIENT_ID": "abc123"
      }
    },
    "another-runtime": {
      "command": "uvx",
      "args": ["cognito-mcp-proxy@latest"],
      "env": {
        "AGENTCORE_REGION": "us-west-2",
        "AGENTCORE_RUNTIME_ID": "arn:aws:bedrock-agentcore:us-west-2:123456:runtime/Other-Runtime",
        "COGNITO_DOMAIN": "https://other-pool.auth.us-west-2.amazoncognito.com",
        "COGNITO_CLIENT_ID": "xyz789"
      }
    }
  }
}

Key Differences from tester_bundle

Feature	tester_bundle (old)	cognito-mcp-proxy (new)
Installation	Manual copy + pip install truststore	uvx cognito-mcp-proxy@latest (zero setup)
Configuration	Edit .env file	Set env vars in mcp.json
Path management	User must locate Python and script path	Automatic via uvx
Upgrades	Manual file replacement	@latest auto-updates
Reuse	One config per .env file	Different env vars per mcp.json entry
Multi-runtime	Copy entire folder per runtime	Just add another mcp.json entry

Development

# Clone and build
cd cognito_mcp_proxy
uv venv
uv pip install -e .

# Run directly
cognito_mcp_proxy

# Test with MCP Inspector
npx @modelcontextprotocol/inspector cognito_mcp_proxy

Build & Publish

uv build
uv publish  # to PyPI

Troubleshooting

Browser doesn't open:

• Check your default browser is set
• Ensure VPN is connected (corporate network required)

"Invalid grant" error:

• Disconnect and reconnect the MCP server in Kiro

Timeout errors:

• Ensure VPN is active
• Increase COGNITO_REQUEST_TIMEOUT if runtime is slow

"Required environment variable X is not set":

• Check your mcp.json env block has all required variables

"AgentCore runtime not configured":

• Set either AGENTCORE_RUNTIME_ID (+ optional AGENTCORE_REGION) or AGENTCORE_RUNTIME_URL

Notes

• No AWS CLI or aws sso login needed
• No credentials saved to disk — tokens live in memory only
• Token auto-refreshes (valid ~30 days)
• If already signed into Microsoft, auth completes with zero clicks
• Corporate SSL handled via truststore package
• Works with any AgentCore runtime — not limited to Redshift