Skip to main content
Glama
deenesjakoruzh
pcolazurdo

blog-zero-secrets-mcp

by pcolazurdo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

AgentCore + Cognito Public Client MCP PoC

端到端概念验证，演示 MCP 服务器在 AgentCore 上的两种部署模式：

  1. 独立模式 — 运行时直接使用 Cognito JWT 认证（无网关）

  2. 网关模式 — 运行时位于 AgentCore Gateway 之后，使用 Cognito PKCE 入站认证和 IAM 出站认证

两种模式均使用公共 Cognito 客户端（无 client_secret），并通过 PKCE 进行用户认证。

架构

模式 A：独立模式（运行时直接使用 JWT 认证）

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

模式 B：网关模式（推荐）

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)

网关模式提供：

  • 集中式认证（网关处理所有 JWT 验证）

  • 跨多个目标的工具发现和语义搜索

  • 协议级 MCP 路由

  • 关注点分离（运行时无需了解用户认证）

Related MCP server: local-kms-mcp-server

项目结构

.
├── 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

快速入门：网关模式（推荐）

步骤 1：安装依赖

npm install

步骤 2：创建 Cognito 基础设施

npm run setup

创建具有公共应用客户端（无密钥）、托管 UI 域和测试用户（testuser / TestPass123!）的 Cognito 用户池。配置保存到 .env。

步骤 3：部署运行时

npm run deploy-runtime

使用 agentcore CLI 将 MCP 服务器部署到 AgentCore Runtime。运行时使用默认的 IAM 认证（网关将负责用户认证）。

步骤 4：部署网关

npm run deploy-infra

创建：

  • 用于网关的 IAM 角色（具有调用运行时的权限）

  • 具有 CUSTOM_JWT 入站认证（Cognito PKCE）的 AgentCore Gateway

  • 通过 GATEWAY_IAM_ROLE（SigV4）指向运行时的网关目标

使用网关 URL 更新 .mcp.json 和 claude-mcp-config.json。

步骤 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 登录。之后，令牌会被自动缓存和刷新。

快速入门：独立模式

如果你不需要网关，并希望运行时直接处理 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 脚本

Script

Description

npm run setup

创建 Cognito 用户池 + 公共客户端 + 测试用户

npm run deploy-runtime

通过 agentcore CLI 部署 MCP 运行时（IAM 认证，用于网关）

npm run deploy-infra

通过 Control Plane API 创建网关 + IAM 角色 + 目标

npm run deploy

使用直接 JWT 认证部署运行时（独立模式，无网关）

npm run test-gateway

端到端测试网关（非交互式）

npm run test-gateway -- --pkce

使用基于浏览器的 PKCE 登录测试网关

npm run test-deployed

通过 PKCE 测试独立运行时

npm run test-auth

仅测试 PKCE 认证流程（打开浏览器）

npm run test-local

在本地运行 MCP 服务器以进行开发

npm run teardown

删除所有基础设施（网关、IAM 角色、Cognito 用户池）

可用的 MCP 工具

示例 MCP 服务器提供：

Tool

Description

add_numbers

将两个数字相加

multiply_numbers

将两个数字相乘

greet_user

按姓名问候用户

get_server_info

返回部署和版本信息

analyze_text

分析文本并返回基本统计信息

通过网关访问时，工具名称会以目标名称作为前缀：mcp-runtime___add_numbers。

清理

npm run teardown

这将删除：

  • AgentCore Gateway（目标 + 网关）

  • 网关 IAM 角色

  • Cognito 用户池

  • 本地文件（.env、.mcp.json、claude-mcp-config.json）

AgentCore Runtime 不会被删除（由 agentcore CLI 单独管理）。要删除它：

cd server/cognitopocmcp && agentcore destroy

关键概念

零密钥认证

  • Cognito 公共客户端：GenerateSecret: false — 不存在客户端密钥

  • PKCE（code_challenge + code_verifier）在无共享密钥的情况下证明请求者身份

  • 本地仅存储 client_id（公共标识符，而非凭据）

  • 令牌保存在内存中，1 小时过期 + 自动刷新

网关出站认证

网关使用自己的 IAM 角色（SigV4）向运行时进行认证。这避免了网关与运行时之间 OAuth 机器对机器流程的复杂性。该 IAM 角色具有限定到运行时 ARN 的 bedrock-agentcore:* 权限。

可移植性

所有环境特定值均在运行时派生：

  • AWS 账户 ID：通过 STS.GetCallerIdentity 解析

  • 网关 URL：从 .mcp.json 读取（由 deploy-infra 生成）

  • 运行时 ARN：从 agentcore 部署状态读取

  • 项目常量：集中在 src/config.mjs 中

要在其他账户/区域部署，只需配置 AWS 凭据并重新运行设置步骤。

安全

有关报告安全问题的信息，请参阅 CONTRIBUTING。

许可证

本库根据 MIT-0 许可证授权。请参阅 LICENSE 文件。

This server cannot be deployed

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers