AgentCore + Cognito Public Client MCP PoC

Сквозная проверка концепции, демонстрирующая два режима развертывания MCP-сервера на AgentCore:

1. Standalone — Runtime с прямой аутентификацией через JWT Cognito (без шлюза)

2. Gateway — Runtime за шлюзом AgentCore с входящей аутентификацией PKCE Cognito и исходящей аутентификацией IAM

Оба режима используют публичный клиент Cognito (без client_secret) с PKCE для аутентификации пользователей.

Архитектура

Режим A: Standalone (Runtime с прямой аутентификацией JWT)

Claude Code / Kiro
    │ PKCE → Cognito Hosted UI → browser
    │ Bearer JWT
    ▼
AgentCore Runtime (CUSTOM_JWT validates token)
    │
    ▼
MCP Server (FastMCP, Python)

Режим B: Gateway (рекомендуется)

Claude Code / Kiro
    │ PKCE → Cognito Hosted UI → browser
    │ Bearer JWT
    ▼
AgentCore Gateway (CUSTOM_JWT validates token)
    │ SigV4 (gateway IAM role)
    ▼
AgentCore Runtime (AWS_IAM auth)
    │
    ▼
MCP Server (FastMCP, Python)

Режим Gateway обеспечивает:

• Централизованную аутентификацию (шлюз обрабатывает всю проверку JWT)

• Обнаружение инструментов и семантический поиск по нескольким целевым ресурсам

• Маршрутизацию MCP на уровне протокола

• Разделение ответственности (Runtime не нужно знать об аутентификации пользователей)

Структура проекта

.
├── server/
│   ├── cognitopocmcp/              # Runtime deployed via agentcore CLI
│   │   ├── app/cognito_poc_mcp/
│   │   │   └── main.py            # FastMCP server with sample tools
│   │   └── agentcore/             # agentcore CLI config
│   ├── mcp_server.py              # MCP server source (standalone mode)
│   └── requirements.txt
├── src/
│   ├── config.mjs                 # Shared config (project name, region, helpers)
│   ├── auth.mjs                   # PKCE auth module (no secrets!)
│   ├── mcp-server.mjs             # Stdio MCP server (proxy mode)
│   └── test-auth.mjs              # Standalone auth flow test
├── scripts/
│   ├── setup-cognito.mjs          # Creates Cognito pool + public client + user
│   ├── deploy.sh                  # Deploys runtime (standalone mode, with JWT auth)
│   ├── deploy-infrastructure.mjs  # Creates gateway + IAM role + target (gateway mode)
│   ├── test-gateway.mjs           # Tests gateway end-to-end
│   ├── test-deployed.mjs          # Tests standalone runtime end-to-end
│   └── teardown-cognito.mjs       # Deletes all infrastructure
├── .env                           # Generated by setup (Cognito config)
├── .mcp.json                      # Generated by deploy-infra (gateway URL + OAuth)
├── claude-mcp-config.json         # Same as .mcp.json (for copying to Claude/Kiro)
└── package.json

Предварительные требования

# AWS CLI + credentials configured
aws sts get-caller-identity

# Node.js 20+
node --version

# AgentCore CLI
npm install -g @aws/agentcore

# Python 3.10+ (for the MCP server)
python3 --version

Быстрый старт: режим Gateway (рекомендуется)

Шаг 1: Установка зависимостей

npm install

Шаг 2: Создание инфраструктуры Cognito

npm run setup

Создает пользовательский пул Cognito с публичным клиентом приложения (без секрета), доменом hosted UI и тестовым пользователем (testuser / TestPass123!). Конфигурация сохраняется в .env.

Шаг 3: Развертывание Runtime

npm run deploy-runtime

Развертывает MCP-сервер в AgentCore Runtime с использованием agentcore CLI. Runtime использует аутентификацию IAM по умолчанию (шлюз будет аутентифицировать пользователей).

Шаг 4: Развертывание шлюза

npm run deploy-infra

Создает:

• Роль IAM для шлюза (с разрешением на вызов Runtime)

• Шлюз AgentCore с входящей аутентификацией CUSTOM_JWT (PKCE Cognito)

• Целевой ресурс шлюза, указывающий на Runtime через GATEWAY_IAM_ROLE (SigV4)

Обновляет .mcp.json и claude-mcp-config.json с URL шлюза.

Шаг 5: Тестирование

npm run test-gateway

Выполняет аутентификацию через Cognito (в неинтерактивном режиме с использованием тестового пользователя), затем:

• Проверяет, что неаутентифицированные запросы отклоняются (401)

• Инициализирует MCP-сессию

• Выводит список обнаруженных инструментов

• Вызывает инструменты (greet_user, add_numbers, get_server_info)

Шаг 6: Подключение Claude Code / Kiro

Скопируйте сгенерированную конфигурацию:

# For Kiro — .mcp.json is already in the project root
# For Claude Code
cp claude-mcp-config.json ~/.claude/mcp.json

Конфигурация выглядит так:

{
  "mcpServers": {
    "cognito-poc": {
      "type": "http",
      "url": "https://<gateway-id>.gateway.bedrock-agentcore.<region>.amazonaws.com/mcp",
      "oauth": {
        "clientId": "<public-client-id>",
        "callbackPort": 8976
      }
    }
  }
}

При первом вызове инструмента Claude/Kiro откроет браузер для входа через Cognito. После этого токены кэшируются и обновляются автоматически.

Быстрый старт: режим Standalone

Если вам не нужен шлюз и вы хотите, чтобы Runtime обрабатывал аутентификацию JWT напрямую:

npm run setup         # Create Cognito pool
npm run deploy        # Deploy runtime with CUSTOM_JWT auth
npm run test-deployed # Test via PKCE (opens browser)

npm-скрипты

Доступные MCP-инструменты

Пример MCP-сервера предоставляет:

При доступе через шлюз имена инструментов получают префикс с именем целевого ресурса: mcp-runtime___add_numbers.

Очистка

npm run teardown

Это удаляет:

• Шлюз AgentCore (целевые ресурсы + шлюз)

• Роль IAM шлюза

• Пользовательский пул Cognito

• Локальные файлы (.env, .mcp.json, claude-mcp-config.json)

Runtime AgentCore НЕ удаляется (управляется отдельно через agentcore CLI). Чтобы удалить его:

cd server/cognitopocmcp && agentcore destroy

Ключевые концепции

Аутентификация без секретов

• Публичный клиент Cognito: GenerateSecret: false — секрет клиента не существует

• PKCE (code_challenge + code_verifier) подтверждает запрашивающую сторону без общего секрета

• Локально сохраняется только client_id (публичный идентификатор, не учетные данные)

• Токены хранятся в памяти со сроком действия 1 час + автоматическое обновление

Исходящая аутентификация шлюза

Шлюз аутентифицируется в Runtime с использованием собственной роли IAM (SigV4). Это позволяет избежать сложности потоков OAuth между машинами (machine-to-machine) между шлюзом и Runtime. Роль IAM имеет разрешение bedrock-agentcore:*, ограниченное ARN Runtime.

Переносимость

Все значения, зависящие от окружения, получаются во время выполнения:

• ID аккаунта AWS: определяется через STS.GetCallerIdentity

• URL шлюза: читается из .mcp.json (создается командой deploy-infra)

• ARN Runtime: читается из состояния развертывания agentcore

• Константы проекта: централизованы в src/config.mjs

Для развертывания в другом аккаунте/регионе просто настройте учетные данные AWS и повторите шаги настройки.

Безопасность

См. CONTRIBUTING для получения информации о сообщении об проблемах безопасности.

Лицензия

Эта библиотека распространяется под лицензией MIT-0. См. файл LICENSE.