docs(decisions): ADR-019 unify agent tools behind an AgentCore Gateway (#641)

[ClintEastman02]

What

Adds ADR-019: Unify agent tools behind an AgentCore Gateway — the tool-plane complement to ADR-016. Records the decision to federate ABCA's agent tools behind an Amazon Bedrock AgentCore Gateway (managed MCP aggregation + dual-sided auth), portable across the AgentCore microVM and ECS/Fargate substrates.

Docs-only: the ADR plus its regenerated Starlight mirror.

Scope (near-term)

Lead with the simplest, most common target type — not the hardest. Per #641, OAuth is one option among several and most targets never touch it; the prior spike's mistake was exercising only a single 3LO-OAuth target. So the ADR phases delivery off the easiest outbound leg:

• P0 — this ADR
• P1 — a Lambda tool target behind the gateway (outbound auth = gateway execution role, no stored credential, no consent flow)
• P2 — substrate parity (microVM + ECS/Fargate) + one credentialed simple target (IAM-signed HTTP/OpenAPI or API-key)
• P3 — generalize to N registry-declared targets (Smithy, no-auth, OAuth 2LO)
• P4 — hardening, semantic search, and the demanding 3LO-OAuth remote-MCP path, exercised last

Linear and Jira MCP are explicitly out of near-term scope. Linear stays deterministic by decision (ADR-016, enforced by strip_linear_mcp_servers()); Jira's live path stays the REST shim (ADR-015). Whether a gateway that owns the OAuth flow could unbreak the non-functional Jira MCP placeholder is recorded as a P4 speculative experiment, gated separately.

Key decisions

1. Gateway is the tool plane, with a direct-MCP fallback retained (additive, no cutover).
2. SigV4 (AWS_IAM) inbound by default; CUSTOM_JWT (Cognito M2M) only where a 3LO OAuth outbound target requires it.
3. Outbound auth branches by target type (execution role / SigV4 / API-key / OAuth 2LO / OAuth 3LO), all vaulted through AgentCore Identity — the credential never enters the container.
4. Targets are registry-declared (consumes the MCP-server asset kind from feat(registry): central agent asset registry for capabilities, skills, plugins, and MCP servers #246 / PR docs(decisions): ADR-018 propose central agent asset registry (#246) #548).

Governance note

Filing this ADR PR as the mechanism to move the #641 decision toward accepted. Implementation PRs (P1+) will follow ADR-003 governance once the decision lands.

Validation

• mise //docs:sync — mirror regenerated and in sync.
• mise //docs:link-check — clean.

Refs #641. Grounded in the feat/agentcore-gateway-mcp spike (verdict: GO) and reference samples aal80/agentcore-samples, aws-samples/sample-agent-assisted-sdlc, awslabs/agentcore-samples (SRE-agent).

[isadeks]

Thanks for writing this up — the general decision is sound and matches the intent of #641: Gateway as a managed tool plane, substrate-portable inbound (SigV4 default / JWT), outbound auth that branches by target type, registry-declared targets, and the tool credential never entering the container. The ADR-016 relationship, the candidate-numbering note, and the astro.config.mjs sidebar fix are all handled well.

However, the near-term scope (Linear + Jira MCP as P1/P2) needs to change before this moves toward accepted. It contradicts #641, reverses ADR-016, and rests on a factual error about the code it cites. Requesting changes on those points; the mechanism itself is fine.

1. Factual error: "the two MCP servers ABCA uses today" — there is one, and it's a non-functional placeholder

The ADR's Context and Scope sections describe agent/src/channel_mcp.py as hosting "the two MCP servers ABCA uses today — Linear and Jira" and calls Linear "functional today via a direct Bearer ${LINEAR_API_TOKEN} entry." The code says the opposite:

• One builder entry exists, not two: CHANNEL_MCP_BUILDERS = { "jira": (...) } — no Linear.
• Linear MCP is not just absent, it's forbidden and actively stripped. The module docstring: "Linear is NOT written here… There is no Linear MCP… The Linear MCP was removed after it proved non-functional." strip_linear_mcp_servers() deletes any Linear MCP entry from .mcp.json before the SDK loads it, on every task, as ADR-016 enforcement.
• Jira's entry is itself a non-functional placeholder (headless OAuth 2.1 can't connect; the live path is the jira_reactions.py REST shim, per ADR-015).

So the count of functional platform-managed MCP servers the agent uses today is zero, and Linear specifically was tried, proven non-functional, removed, and is now scrubbed. The ADR should state this accurately.

2. Scope contradicts #641

#641 was written specifically to steer away from a Linear-first cut:

• The spike branch is "Linear-coupled and out of scope — use it as a reference for the mechanism, not a base… do NOT continue off it."
• "Test multiple target TYPES (not just one OAuth server). The prior spike only exercised a single 3LO-OAuth MCP-server target."
• "OAuth is one option among several… most targets we'd add never touch OAuth", and "the UX must not make API-key / IAM / 2LO targets pay [the 3LO] cost."

This ADR makes Linear + Jira — both 3LO-OAuth remote MCP servers, the single hardest auth path — the P1/P2 deliverable, and frames it as a positive ("the near-term tests exercise the hardest auth path"). That's the opposite of what #641 asked: lead with the simpler, common target types.

3. The ADR-016 reversal can't be deferred

The ADR's ADR-016 tension callout is honest and appreciated — but it treats the conflict as a "follow-up, not resolved unilaterally in this ADR." It's the crux, not a footnote: ADR-016 + shipping enforcement code (strip_linear_mcp_servers) mandate that the agent has no Linear MCP, while this ADR's P1 is "route Linear MCP through an agent-reachable gateway." An ADR can't reach accepted when its first deliverable is barred by an accepted ADR and by enforcement code in the tree. This must be resolved (reconcile or explicit carve-out) before landing, not after.

4. "Admin direction" isn't reflected in #641

The Linear+Jira scope is attributed to "admin direction," but #641 contains no such scoping — it de-scopes Linear. If there is a separate directive, please reconcile it with #641 and ADR-016 in writing; as it stands the ADR and its originating issue disagree on scope.

---

Suggested change — keep the mechanism, swap the exemplar

The decision is good; only the near-term exemplar is wrong. Concretely:

• Pick a near-term target ABCA actually wants the agent to hold as an MCP tool — a Lambda tool, an IAM-signed internal service, or an API-key service. This exercises the simpler, common auth paths first (what #641 asked), proves substrate portability on both microVM and ECS/Fargate, and introduces no ADR-016 conflict.
• Remove Linear and Jira from P1/P2. Linear is deterministic by decision (ADR-016); Jira's real path is the REST shim (ADR-015). If "can a gateway unbreak the non-functional Jira MCP placeholder?" is worth exploring, record it as a speculative later experiment, explicitly noting it does not re-introduce agent-side Linear/Jira MCP into the deterministic reaction/orchestration paths.
• Fix the factual claims in Context/Scope about channel_mcp.py (one entry, non-functional; Linear removed and stripped per ADR-016).

Happy to pair on the revised scope. I'll also drop a note on #641 clarifying that Linear/Jira MCP is explicitly not the goal so this doesn't recur.

[ClintEastman02]

Thanks for the thorough review — agreed on all four points, and the mechanism-vs-exemplar framing was exactly the right cut. Addressed in fdae556:

1. Facts corrected (Context + Scope). The ADR now states plainly that ABCA holds zero functional platform-managed MCP servers today: the single CHANNEL_MCP_BUILDERS entry is jira and it's a non-functional placeholder (headless OAuth 2.1 can't connect; live path is the REST shim in jira_reactions.py, ADR-015). Linear is documented as deterministic-by-decision (ADR-016) — removed after proving non-functional and actively stripped by strip_linear_mcp_servers() before the SDK loads .mcp.json. No more "two MCP servers / Linear functional" claims.

2. Scope realigned to feat(registry): unify agent tools behind an AgentCore Gateway (managed MCP aggregation + dual-sided auth, any substrate) #641 — lead with the simplest target, not the hardest. P1 now onboards a Lambda tool target: outbound auth is the gateway execution role (IAM), no stored credential and no consent flow, proving the end-to-end path (provisioning, substrate-portable inbound, aggregation, agent routing) on the easiest outbound leg. The 3LO-OAuth remote-MCP path is now exercised last (P4), not first.

3. ADR-016 reversal removed, not deferred. Linear + Jira are out of near-term scope entirely, so there's no reversal left to reconcile. Linear stays deterministic (ADR-016); Jira's live path stays the REST shim (ADR-015). The "can a gateway unbreak the non-functional Jira MCP placeholder?" question is demoted to a separately-gated speculative P4 experiment that explicitly does not re-introduce agent-side Linear/Jira MCP into the deterministic reaction/orchestration paths.

4. "Admin direction" framing dropped. Removed the attribution and the deferred ADR-016 tension callout — the ADR no longer contradicts feat(registry): unify agent tools behind an AgentCore Gateway (managed MCP aggregation + dual-sided auth, any substrate) #641 on scope.

Phasing table and Testing section were reordered to match (P1 = Lambda/no-credential; the target × auth matrix broadens from simplest to hardest).