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

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

{
  "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": []
    }
  }
}

{
  "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

chmod +x Build_Test_Deploy.sh
./Build_Test_Deploy.sh

# 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

npx @modelcontextprotocol/inspector $(which agentcore_mcp_proxy)

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

# Production PyPI
uv publish

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

lsof -ti :8080 | xargs kill -9

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

mwinit
# Or use Cognito User authentication instead

rm -rf ~/.agentcore_mcp_proxy/