# 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](SECURITY.md).

---


## Kiro IDE Configuration

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

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

```json
{
  "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:

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

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

```bash
npx @modelcontextprotocol/inspector $(which agentcore_mcp_proxy)
```

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

### Publishing to PyPI

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

# Production PyPI
uv publish
```

After publishing, users can install with:
```bash
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:
```bash
lsof -ti :8080 | xargs kill -9
```

### "Encryption key mismatch"

Tokens were copied from another machine or hardware changed:
```bash
rm -rf ~/.agentcore_mcp_proxy/
# Re-authenticate on next use
```

### "Missing required environment variables"

Ensure all required env vars are set. See [Environment Variables](#environment-variables) above.

### No Midway Session (Federate only)

```bash
mwinit
# Or use Cognito User authentication instead
```

### Gateway 401 Unauthorized

Delete cached tokens and re-authenticate:
```bash
rm -rf ~/.agentcore_mcp_proxy/
```

## License

MIT License — See [LICENSE](LICENSE) file.