MCP External Access AWS Technical Review 2026 07 22 - TerrenceMcGuinness-NOAA/global-workflow GitHub Wiki

MCP External Access — AWS Technical Review Report

Date: July 22, 2026 Prepared for: AWS Management Team Technical Review (first cadence meeting) Status: Implementation complete (CDK + Lambda + tests); NOT deployed pending dual-auth verification Branch: feature/congnito_endpoint (commit ee91663) Spec: .kiro/specs/mcp-external-access-revised/

1. Executive Summary

The MDC MCP RAG Server — NOAA's AI-powered code analysis platform (52 tools, Neptune graph + OpenSearch vectors, serving 5 multi-tenant workflow branches) — is currently accessible only from an EC2 developer workstation via IAM SigV4. This spec extends access to GitHub Actions CI/CD pipelines and HPC user sessions (Hera, Orion, Hercules, Gaea) via Cognito-backed JWT Bearer tokens, without breaking the existing developer path.

Implementation status: Tasks 1–5 of 13 complete. CDK stack authored, tested (53 tests pass), and synthesized. One critical verification point (C8: dual-auth mode) requires AWS confirmation before deployment.

2. Architecture — Current State

+------------------------------------------------------------------+
|  TODAY: Single-Consumer, IAM SigV4 Only                          |
|                                                                  |
|  +--------------------+        SigV4          +--------------+   |
|  | EC2 Dev Workstation|---------------------->|  AgentCore   |   |
|  | (agentcore-kiro-   |  invoke_agent_runtime |  Runtime     |   |
|  |  proxy.py)         |                       |  Python v11  |   |
|  +--------------------+                       |  52 tools    |   |
|                                               |  Neptune +   |   |
|  X GitHub Actions -- cannot reach             |  OpenSearch  |   |
|  X HPC users -- cannot reach                  +--------------+   |
|  X External collaborators -- cannot reach                        |
+------------------------------------------------------------------+

3. Architecture — Proposed (Path B: Cognito JWT on AgentCore Runtime)

+----------------------------------------------------------------------------+
|  PROPOSED: Multi-Consumer, Dual-Auth (SigV4 + JWT)                         |
|                                                                            |
|  +---------------------+                                                   |
|  | EC2 Dev Workstation |---- SigV4 (unchanged) ----+                       |
|  | (agentcore-kiro-    |                           |                       |
|  |  proxy.py)          |                           v                       |
|  +---------------------+                   +--------------+                |
|                                            |  AgentCore   |                |
|  +---------------------+   JWT Bearer      |  Runtime     |                |
|  | GitHub Actions       |----------------->|  + JWT       |                |
|  | Runner               |                  |  Authorizer  |                |
|  +----------+----------+                   |  (Cognito)   |                |
|             |                              |              |                |
|             | GitHub OIDC                  |  52 tools    |                |
|             v                              |  Neptune +   |                |
|  +-----------------------+                 |  OpenSearch  |                |
|  | Token_Broker Lambda   |--client_creds-->+--------------+                |
|  | (OIDC -> JWT exchange)|     ^                                           |
|  +-----------------------+     |                                           |
|                                | JWT Bearer                                |
|  +---------------------+       |                                           |
|  | HPC User (Hera,     |-------+                                           |
|  | Orion, Hercules...) |  Auth Code + PKCE                                 |
|  | via HPC_CLI_Helper  |  (Cognito Hosted UI)                              |
|  +---------------------+                                                   |
|                                                                            |
|  +-----------------------------------------------------------------------+ |
|  |  Cognito User Pool                                                    | |
|  |  +-- Resource Server: mcp (scopes: ci-readonly, hpc-user)             | |
|  |  +-- CI_App_Client (client-credentials, mcp/ci-readonly)              | |
|  |  +-- HPC_App_Client (auth-code+PKCE + SRP, mcp/hpc-user)              | |
|  |  +-- Hosted UI: mdc-mcp-external-alt.auth.us-east-1.amazoncognito.com | |
|  +-----------------------------------------------------------------------+ |
+----------------------------------------------------------------------------+

4. Architecture — Fallback (Path C: AgentCore Gateway)

If dual-auth (SigV4 + JWT on the same Runtime) is confirmed as NOT supported:

+-----------------------------------------------------------------------------+
|  FALLBACK (Path C): Gateway fronts Runtime                                  |
|                                                                             |
|  +---------------------+                                                    |
|  | EC2 Dev Workstation |---- SigV4 (direct to Runtime, unchanged) ---+      |
|  +---------------------+                                             |      |
|                                                                      v      |
|  +---------------------+   JWT Bearer    +--------------+   SigV4  +-----+  |
|  | GitHub Actions      |---------------->|  AgentCore   |--------->| RT  |  |
|  | + HPC Users         |                 |  Gateway     |          |     |  |
|  +---------------------+                 |  (JWT auth)  |          | 52  |  |
|                                          |  + Cedar     |          |tools|  |
|                                          |  policies    |          |     |  |
|                                          +--------------+          +-----+  |
|                                                                             |
|  Developer path: EC2 -> Runtime (SigV4, bypasses Gateway)                   |
|  External path: CI/HPC -> Gateway (JWT) -> Runtime (SigV4 internally)       |
+-----------------------------------------------------------------------------+

Path C advantages (if dual-auth is not available):

  • Runtime stays SigV4-only → developer path unaffected
  • Gateway provides tool-level Cedar policy authorization
  • Stable URL decoupled from Runtime redeploys
  • Cross-account resource policies possible

Path C cost: Additional Gateway construct in CDK; slightly higher latency (one extra hop).

5. Consumer Classes and Scope Model

Consumer Auth method Cognito scope Tool access Use case
Developer (existing) IAM SigV4 N/A All 52 tools (full access) Interactive development, Kiro IDE
CI Pipeline (new) JWT (client-credentials) mcp/ci-readonly Read-only subset (~45 tools; mutations blocked) EE2 root-cause analysis on failed builds
HPC User (new) JWT (auth-code + PKCE) mcp/hpc-user Read-only + personal-tenant write Meteorologists on Hera/Orion/Hercules/Gaea

Mutation tools blocked for CI/HPC (7): mark_as_modified, checkpoint_state, restore_checkpoint, start_sdd_session, record_sdd_step, complete_sdd_session, mcp_create_profile.

6. Token Flow — GitHub Actions (CI)

+------------------------------------------------------------------+
|  GitHub Actions Workflow                                         |
|                                                                  |
|  1. Runner assumes OIDC role:                                    |
|     aws sts assume-role-with-web-identity                        |
|       --role-arn arn:aws:iam::903050880929:role/mdc-mcp-alt-...  |
|       --web-identity-token $ACTIONS_ID_TOKEN                     |
|                                                                  |
|  2. Invoke Token_Broker Lambda:                                  |
|     { github_claims: { sub, run_id, repository, ref } }          |
|                                                                  |
|  3. Token_Broker:                                                |
|     - Validates sub against allowlist (NOAA-EMC repos only)      |
|     - Fetches CI client secret from Secrets Manager              |
|     - Calls Cognito /oauth2/token (client_credentials)           |
|     - Returns: { access_token, request_id }                      |
|     - Logs structured attribution (join key = request_id)        |
|                                                                  |
|  4. Runner calls MCP endpoint:                                   |
|     Authorization: Bearer <access_token>                         |
|     X-Request-Id: <request_id>                                   |
|                                                                  |
|  5. AgentCore validates JWT -> routes to MCP_Server              |
|     MCP_Server: toolScopeGuard checks scope -> allows/blocks     |
|     Audit log: caller_sub + request_id + tool_name + timestamp   |
+------------------------------------------------------------------+

7. Token Flow — HPC Users

+------------------------------------------------------------------+
|  HPC Login Node (Hera, Orion, Hercules, Gaea)                    |
|                                                                  |
|  Primary path (has browser access):                              |
|  1. User runs: mcp-auth login                                    |
|  2. Opens browser -> Cognito Hosted UI                           |
|  3. Authenticates (username/password or SSO)                     |
|  4. Authorization Code + PKCE exchange (loopback redirect)       |
|  5. Receives JWT -> cached locally (~1 hour TTL)                 |
|                                                                  |
|  Headless fallback (no browser):                                 |
|  1. User runs: mcp-auth login --headless                         |
|  2. SRP (Secure Remote Password) auth directly to Cognito        |
|  3. No browser, no redirect -- password never leaves the node    |
|  4. Receives JWT -> cached locally                               |
|                                                                  |
|  Usage:                                                          |
|  mcp-query --tool search_documentation --query "JGDAS analysis"  |
|  -> reads cached JWT, calls MCP endpoint with Bearer token       |
+------------------------------------------------------------------+

8. CDK Stack Composition

MdcExternalAccessAlternativeStack
├── Cognito User Pool (RETAIN)
│   ├── Resource Server: mcp
│   │   ├── Scope: ci-readonly
│   │   └── Scope: hpc-user
│   ├── Hosted UI Domain: mdc-mcp-external-alt
│   ├── CI_App_Client (client-credentials only)
│   └── HPC_App_Client (auth-code+PKCE + SRP)
├── Secrets Manager Secret (RETAIN) — CI client_id + client_secret
├── Token_Broker Lambda (Python 3.12)
│   ├── Log Group (RETAIN, 90 days)
│   ├── Resource Policy (invoke from OIDC role)
│   └── Reserved Concurrency: 10
├── JWT Authorizer (AwsCustomResource → updateAgentRuntime)
│   ├── Full lossless runtime payload + customJWTAuthorizer
│   └── Drift Detector Alarm (CloudWatch)
└── Outputs
    ├── McpEndpointUrl
    ├── HpcUserPoolId
    ├── CiAppClientId
    └── TokenBrokerArn

IAM resources NOT in stack (admin pre-created, imported):

  • GitHub OIDC provider (token.actions.githubusercontent.com)
  • mdc-mcp-alt-gh-oidc-ci (CI federated role)
  • mdc-mcp-alt-token-broker-role (Lambda execution role)
  • mdc-mcp-alt-custom-resource-role (for the updateAgentRuntime call)

9. Security Posture

Control Implementation NIST 800-53
No long-lived tokens on HPC JWT TTL ~1 hour; SRP password never transmitted plaintext IA-5
Least privilege per consumer Scope-based tool filtering; mutations blocked for CI/HPC AC-6
No CI secrets in code GitHub OIDC federation → no stored credentials IA-5(2)
Audit every tool call Structured CloudWatch log (caller, tool, timestamp, request_id) AU-2, AU-3
Drift detection Authorizer config alarm; daily reconciliation script CM-6, CA-7
Network: no new ingress AgentCore public endpoint (already exists); no new VPC rules SC-7
Data safety RETAIN on all stateful resources; zero Neptune/OpenSearch/EFS in stack CP-9

10. Decision Point: Dual-Auth Verification (C8)

The question

Does AgentCore Runtime support SigV4 AND JWT simultaneously on the same endpoint? Or does attaching a customJWTAuthorizer replace SigV4 as the inbound auth mode?

Evidence so far

The Task 0 gate test (curl with a fake Bearer token) returned:

HTTP 403
{"message":"Authorization method mismatch. The agent is configured for
a different authorization method than what was used in your request. Check
the agent's authorization configuration and ensure your request uses the
matching method (OAuth or SigV4)"}

The phrasing "OAuth or SigV4" (not "OAuth and SigV4") suggests single-mode.

Options

Option Approach Risk Timeline
A Ask AWS specialist to confirm dual-auth behavior Zero risk 1–3 days (next cadence meeting)
B Create a throwaway test runtime, attach JWT, verify SigV4 still works Low risk (disposable runtime) ~1 hour
C Assume single-mode; pivot now to Path C (Gateway) Zero data risk 3–5 days additional CDK work

Recommendation for the AWS technical review

Option A — present this question at the first cadence meeting. The answer determines whether we deploy Path B as-built (Tasks 1–5 are complete) or extend to Path C (Gateway fronting the Runtime). Either way:

  • All Cognito, Token_Broker, OIDC, and CDK work carries forward unchanged
  • Only the "last mile" routing differs (direct-to-Runtime vs via-Gateway)

11. Implementation Progress

Task Description Status Verified
0 Pre-implementation gate (endpoint reachable?) PASS HTTP 403, endpoint reachable
1 CDK stack scaffold DONE tsc clean, cdk synth OK
2 Cognito pool + clients + Hosted UI DONE 11 CDK tests pass
3 GitHub OIDC federated IAM role (imported) DONE Admin-request doc authored
4 Token_Broker Lambda DONE 4 Python tests pass
5 JWT authorizer (AwsCustomResource) + drift detector DONE Full lossless payload verified
6 MCP_Server middleware (toolScopeGuard + audit) Pending —
7 GitHub composite action Pending —
8 HPC CLI helper Pending —
9 Developer SigV4 regression suite Pending —
10 Network verification Pending —
11 Documentation (runbooks) Pending —
12 CDK diff guardrails Pending —
13 End-to-end acceptance Pending —

Tests: 53/53 CDK jest + 4/4 Python handler = 57 total, all passing.

12. Pre-Deploy Checklist (for AWS Review)

Before cdk deploy:

  • C8 resolved: AWS confirms dual-auth OR we pivot to Path C
  • Admin creates: OIDC provider + 3 IAM roles (per docs/mdc-external-access-alt-iam-request.txt)
  • Operator runs cdk diff and records output (R12 guardrail)
  • Developer regression: verify 52/52 tools via SigV4 post-deploy (Task 9)
  • Rollback plan: the CDK custom resource carries the authorizer-free config as a rollback target

13. Cost Impact

Resource Monthly cost Notes
Cognito User Pool (free tier) $0 < 50K MAU free
Secrets Manager (1 secret) $0.40 $0.40/secret/month
Token_Broker Lambda ~$0 Reserved concurrency 10; invoked only on CI runs
CloudWatch Logs (90-day retention) ~$1–5 Depends on CI run frequency
CloudWatch Alarm (drift detector) $0.10 1 metric alarm
Total incremental < $6/month

No additional VPC resources, NAT Gateways, or data-transfer costs.

14. Questions for the AWS Technical Specialist

  1. Dual-auth mode: Does customJWTAuthorizer on an AgentCore Runtime work alongside SigV4 invoke_agent_runtime, or does it replace SigV4 as the only inbound auth method?

  2. AgentCore Gateway availability: If single-mode is confirmed, is AgentCore Gateway (Path C) GA in us-east-1? What's the CDK construct name?

  3. Cedar policy integration: Can tool-level authorization (scope → allowed tools) be enforced at the Gateway/Runtime level, or must it be application-side middleware?

  4. GitHub OIDC provider: Any account-level restrictions on creating the token.actions.githubusercontent.com OIDC provider? (We know PowerUser can't; does the admin role have restrictions?)

  5. Token TTL: For the CI client-credentials flow, what's the recommended Cognito access-token TTL? (We're using 1 hour; is shorter advisable for CI?)

15. Timeline

Phase Work ETA
Done Tasks 0–5 (CDK + Cognito + Lambda + authorizer) Complete
Blocked on C8 Deploy decision (dual-auth or Gateway pivot) AWS review meeting
After C8 resolution Tasks 6–13 (middleware, composite action, CLI, e2e) 1–2 weeks
Production-ready GitHub Actions consuming MCP tools on CI failures ~3 weeks from C8 resolution

Report prepared for the AWS Management Team Technical Review cadence. All implementation artifacts are on branch feature/congnito_endpoint (commit ee91663). Contact: Terry McGuinness (OMD CAT).

⚠️ **GitHub.com Fallback** ⚠️