agentcore-mcp-proxy 0.1.0

MCP server for any AWS AgenCore Gateway endpoint with Cognito authentication and hardware-bound token encryption

Social Media Tracker MCP Server

An MCP (Model Context Protocol) server that bridges Kiro IDE with the Social Media Tracker AgentCore Gateway. It provides secure, authenticated access to customer intelligence tools including activity tracking, hashtag analytics, geographic distribution, and territory management.

Architecture

┌─────────┐       stdio        ┌──────────┐      HTTPS       ┌──────────────────┐
│  Kiro   │◀──────────────────▶│   MCP    │◀────────────────▶│   AgentCore      │
│   IDE   │                    │  Server  │                   │   Gateway        │
└─────────┘                    └──────────┘                   └──────────────────┘
                                    │                                  │
                                    │                                  │
                               ┌────┴────┐                    ┌───────┴────────┐
                               │ Cognito │                    │  Social Media  │
                               │  OAuth  │                    │  Tracker API   │
                               └─────────┘                    └────────────────┘

1. Kiro IDE communicates with the MCP server over stdio
2. MCP server 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
• 🔒 Hardware-Bound Encryption: Tokens encrypted with machine-specific UUID (non-portable)
• 🛠️ Dynamic Tool Discovery: Tools auto-discovered from AgentCore Gateway
• 🌐 Cross-Platform: macOS, Linux, and Windows
• 📦 Easy Installation: uvx or pip

Available Tools

Tool	Description
list_territories	List all territories with company counts
list_customers	List customers with optional search and insights
get_customer	Get detailed customer information
get_activities_by_customer	Get activities for specific customers
get_activities_by_source	Get activities from a specific source (X, LinkedIn, news, blog)
get_activity_frequency	Time-series activity frequency data
get_activity_heatmap	Activity counts by customer and source
get_activity_velocity	Activity percentage change between periods
get_geo_distribution	Geographic distribution of activities
get_hashtag_analytics	Hashtag distribution with engagement metrics
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
• Hardware-bound token encryption (AES-256, non-portable across machines)
• ID Token used for gateway authorization (contains user identity claims)
• Automatic token refresh with 30-day validity
• Tokens stored encrypted at ~/.agentcore_mcp_proxy/tokens.enc

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

---

Kiro IDE Configuration

Option 1: Using uvx (Recommended — after PyPI publishing)

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

{
  "mcpServers": {
    "agentcore_mcp_proxy": {
      "command": "uvx",
      "args": ["agentcore_mcp_proxy@latest"],
      "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"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Option 2: Using local Python (Development)

{
  "mcpServers": {
    "agentcore_mcp_proxy": {
      "command": "/path/to/your/.venv/bin/python3",
      "args": ["/path/to/proxy_mcp_server/src/agentcore_mcp_proxy/server.py"],
      "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"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Option 3: Using uvx with local source

{
  "mcpServers": {
    "agentcore_mcp_proxy": {
      "command": "uvx",
      "args": ["--from", "/path/to/proxy_mcp_server", "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"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

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://)
AMAZON_IDP_NAME	No	Identity provider name (default: federate)
PROXY_HOST	No	Callback host (default: localhost)
PROXY_PORT	No	Callback port (default: 8080)

See .env.sample for a template.

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)
• npx (for MCP Inspector testing)

Quick Start

# 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.