AgentCore MCP Proxy

A generic MCP (Model Context Protocol) proxy server that bridges AI IDEs (Kiro, Claude Desktop, etc.) with any AWS Bedrock AgentCore Gateway. It provides secure, authenticated access to tools exposed by AgentCore endpoints using Cognito OAuth authentication and hardware-bound token encryption.

Multiple AgentCore gateways can be configured simultaneously — each gets isolated token storage so they never interfere with each other.

Architecture

┌─────────┐       stdio        ┌──────────┐      HTTPS       ┌──────────────────┐
│  Kiro   │◀──────────────────▶│   MCP    │◀────────────────▶│   AgentCore      │
│   IDE   │                    │  Proxy   │                  │   Gateway        │
└─────────┘                    └──────────┘                  └──────────────────┘
                                    │                                  │
                                    │                                  │
                               ┌────┴────┐                    ┌───────┴────────┐
                               │ Cognito │                    │  Your Backend  │
                               │  OAuth  │                    │     APIs       │
                               └─────────┘                    └────────────────┘

1. Kiro IDE communicates with the MCP proxy over stdio
2. Proxy authenticates via Cognito OAuth (browser-based)
3. Authenticated requests are forwarded to AgentCore Gateway over HTTPS
4. Tools are dynamically discovered from the gateway (no hardcoding)

Key Components

File	Purpose
server.py	MCP server with stdio transport, tool discovery, and error handling
auth_manager.py	Dual auth (Federate + Cognito User), OAuth flow, token caching
token_encryption.py	Hardware-bound AES-256 encryption using machine UUID
gateway_client.py	Strands MCPClient integration with Bearer token auth
config.py	Environment-based configuration with validation

Features

• 🔐 Dual Authentication: Amazon Corporate SSO (Federate) or Cognito User Pool
• 🔄 Automatic Token Refresh: 30-day validity with transparent refresh
• 🔒 OS Keyring Integration: Encryption keys stored in macOS Keychain, Windows Credential Locker, or Linux Secret Service (file-based fallback for headless environments)
• 🔑 Hardware-Bound Encryption: Tokens encrypted with machine-specific UUID (non-portable)
• 🌐 Multi-Gateway Support: Configure multiple AgentCore endpoints simultaneously with isolated token storage per gateway
• 🛠️ Dynamic Tool Discovery: Tools auto-discovered from AgentCore Gateway
• 🖥️ Cross-Platform: macOS, Linux, and Windows
• 📦 Easy Installation: uvx or pip

Available Tools

Tools are dynamically discovered from the AgentCore Gateway at startup — no hardcoding required. Whatever tools your gateway exposes will automatically appear in your IDE.

Additionally, if AMAZON_IDP_NAME is configured, two authentication management tools are exposed:

Tool	Description
authenticate_with_federate	Initiate Amazon Corporate SSO authentication
authenticate_with_cognito_user	Initiate Cognito User Pool authentication

Security Overview

The server implements multi-layered security:

• OAuth 2.0 Authorization Code Flow with AWS Cognito
• Encryption keys stored in OS keyring (macOS Keychain / Windows Credential Locker / Linux Secret Service) with file-based fallback
• Hardware-bound token encryption (AES-256, non-portable across machines)
• Per-gateway token isolation — each AGENTCORE_GATEWAY_URL gets its own encrypted token store
• ID Token used for gateway authorization (contains user identity claims)
• Automatic token refresh with 30-day validity

Token storage layout:

~/.agentcore_mcp_proxy/
├── <hash-of-gateway-url-1>/
│   └── tokens.enc
├── <hash-of-gateway-url-2>/
│   └── tokens.enc

For the full security architecture, threat model, and cryptographic details, see SECURITY.md.

---

Kiro IDE Configuration

Add to ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "agentcore_mcp_proxy": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sameerbattoo/awsagentcore_proxy_mcp_server.git",
        "agentcore_mcp_proxy"
      ],
      "env": {
        "AGENTCORE_GATEWAY_URL": "https://your-gateway.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp",
        "COGNITO_USER_POOL_ID": "us-west-2_XXXXXXXXX",
        "COGNITO_CLIENT_ID": "your_client_id_here",
        "COGNITO_DOMAIN": "your-domain.auth.us-west-2.amazoncognito.com",
        "TOKEN_TYPE": "id_token"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Multiple Gateways

You can configure multiple AgentCore endpoints simultaneously. Each entry gets its own isolated token storage (keyed by a SHA-256 hash of the gateway URL), so they never interfere with each other:

{
  "mcpServers": {
    "gateway_a": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sameerbattoo/awsagentcore_proxy_mcp_server.git",
        "agentcore_mcp_proxy"
      ],
      "env": {
        "AGENTCORE_GATEWAY_URL": "https://gateway-a.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp",
        "COGNITO_USER_POOL_ID": "us-west-2_AAAAAAA",
        "COGNITO_CLIENT_ID": "client_id_a",
        "COGNITO_DOMAIN": "domain-a.auth.us-west-2.amazoncognito.com",
        "TOKEN_TYPE": "id_token"
      }
    },
    "gateway_b": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sameerbattoo/awsagentcore_proxy_mcp_server.git",
        "agentcore_mcp_proxy"
      ],
      "env": {
        "AGENTCORE_GATEWAY_URL": "https://gateway-b.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp",
        "COGNITO_USER_POOL_ID": "us-east-1_BBBBBBB",
        "COGNITO_CLIENT_ID": "client_id_b",
        "COGNITO_DOMAIN": "domain-b.auth.us-east-1.amazoncognito.com",
        "TOKEN_TYPE": "id_token"
      }
    }
  }
}

### Environment Variables

All configuration is via environment variables (set in `env` block above or via `.env` file):

| Variable | Required | Description |
|----------|----------|-------------|
| `AGENTCORE_GATEWAY_URL` | Yes | AgentCore Gateway endpoint URL |
| `COGNITO_USER_POOL_ID` | Yes | Cognito User Pool ID |
| `COGNITO_CLIENT_ID` | Yes | Cognito App Client ID |
| `COGNITO_DOMAIN` | Yes | Cognito Domain (without `https://`) |
| `TOKEN_TYPE` | No | Token sent to gateway: `access_token` (default) or `id_token` |
| `AMAZON_IDP_NAME` | No | Identity provider name for Federate SSO (omit to skip Federate) |
| `PROXY_HOST` | No | Callback host (default: `localhost`) |
| `PROXY_PORT` | No | Callback port (default: `8080`) |

See `.env.sample` for a template.

#### TOKEN_TYPE

Controls which Cognito token is sent to the AgentCore Gateway as the Bearer token. Defaults to `access_token`. Set to `id_token` if your gateway needs user identity claims (e.g. `cognito:username`, `email`) for authorization or territory-based access control.

#### AMAZON_IDP_NAME

When set, enables dual authentication mode: users can choose between Amazon Corporate SSO (Federate/Midway) and Cognito User Pool login. The value should match the identity provider name configured in your Cognito User Pool (e.g. `Amazon`, `federate`). When omitted, the server skips Federate entirely and goes straight to Cognito User Pool authentication.

### First-Time Setup

1. Add the MCP configuration to `~/.kiro/settings/mcp.json`
2. Restart Kiro IDE
3. On first tool call, a browser window opens for Cognito authentication
4. Complete login (Amazon SSO or username/password)
5. Tokens are cached encrypted for 30 days with automatic refresh

### Verifying Connection

After configuration, the MCP server appears in Kiro's MCP panel. Verify by asking Kiro to "list my territories" or "list customers".

---

## Building and Testing Locally

### Prerequisites

- Python 3.10+
- `uv` package manager ([install guide](https://docs.astral.sh/uv/getting-started/installation/))
- `npx` (for MCP Inspector testing)

### Quick Start

```bash
# Clone and setup
git clone <repo-url>
cd proxy_mcp_server
uv venv
source .venv/bin/activate

# Install in development mode
uv pip install -e .

# Configure environment
cp .env.sample .env
# Edit .env with your values

# Run the server
agentcore_mcp_proxy

Build, Test & Deploy Script

The repository includes Build_Test_Deploy.sh which automates the full pipeline:

chmod +x Build_Test_Deploy.sh
./Build_Test_Deploy.sh

The script performs these steps:

1. Cleans previous builds
2. Builds the package with uv build
3. Installs in editable mode for testing
4. Verifies the installation (import check + entry point)
5. Opens MCP Inspector for interactive testing (http://localhost:6274)
6. Guides you through Kiro testing
7. Deploys to TestPyPI or PyPI

Manual Build Steps

# Clean
rm -rf dist/ build/ *.egg-info

# Build
uv build

# Install locally
uv pip install -e . --force-reinstall --no-deps

# Verify
python -c "from agentcore_mcp_proxy import main; print('OK')"
which agentcore_mcp_proxy

Testing with MCP Inspector

npx @modelcontextprotocol/inspector $(which agentcore_mcp_proxy)

Opens a browser at http://localhost:6274 where you can interactively test tools.

Publishing to PyPI

# TestPyPI (recommended first)
uv publish --publish-url https://test.pypi.org/legacy/

# Production PyPI
uv publish

After publishing, users can install with:

uvx agentcore_mcp_proxy@latest
# or
pip install agentcore-mcp-proxy

---

Troubleshooting

Port 8080 Already in Use

The server automatically kills blocking processes. If that fails:

lsof -ti :8080 | xargs kill -9

"Encryption key mismatch"

Tokens were copied from another machine or hardware changed:

rm -rf ~/.agentcore_mcp_proxy/
# Re-authenticate on next use

"Missing required environment variables"

Ensure all required env vars are set. See Environment Variables above.

No Midway Session (Federate only)

mwinit
# Or use Cognito User authentication instead

Gateway 401 Unauthorized

Delete cached tokens and re-authenticate:

rm -rf ~/.agentcore_mcp_proxy/

License

MIT License — See LICENSE file.