-
Notifications
You must be signed in to change notification settings - Fork 0
MCP External Access AWS Technical Review 2026 07 22
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/
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.
+------------------------------------------------------------------+
| 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 |
+------------------------------------------------------------------+
+----------------------------------------------------------------------------+
| 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 | |
| +-----------------------------------------------------------------------+ |
+----------------------------------------------------------------------------+
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).
| 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.
+------------------------------------------------------------------+
| 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 |
+------------------------------------------------------------------+
+------------------------------------------------------------------+
| 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 |
+------------------------------------------------------------------+
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)
| 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 |
Does AgentCore Runtime support SigV4 AND JWT simultaneously on the same
endpoint? Or does attaching a customJWTAuthorizer replace SigV4 as the
inbound auth mode?
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.
| 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 |
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)
| 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.
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 diffand 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
| 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.
-
Dual-auth mode: Does
customJWTAuthorizeron an AgentCore Runtime work alongside SigV4invoke_agent_runtime, or does it replace SigV4 as the only inbound auth method? -
AgentCore Gateway availability: If single-mode is confirmed, is AgentCore Gateway (Path C) GA in
us-east-1? What's the CDK construct name? -
Cedar policy integration: Can tool-level authorization (scope → allowed tools) be enforced at the Gateway/Runtime level, or must it be application-side middleware?
-
GitHub OIDC provider: Any account-level restrictions on creating the
token.actions.githubusercontent.comOIDC provider? (We know PowerUser can't; does the admin role have restrictions?) -
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?)
| 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).