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 MCP servers behind an Amazon Bedrock AgentCore Gateway (managed MCP aggregation + dual-sided auth), portable across the AgentCore microVM and ECS/Fargate substrates.

Docs-only. Also folds in a one-line fix to docs/astro.config.mjs (the Decisions sidebar group used items: [{ autogenerate }]; Starlight requires autogenerate as a sibling of label — the nested form was failing astro check on main).

Scope (near-term)

Per admin direction, the near-term scope is Linear + Jira — the only two platform-managed MCP servers in the repo today (agent/src/channel_mcp.py). The ADR generalizes the model but phases delivery:

• P0 — this ADR
• P1 — Linear behind the gateway
• P2 — Jira + substrate parity
• P3 — generalize to N registry-declared targets
• P4 — hardening + semantic search

Key decisions

1. Gateway is the tool plane, with a direct-MCP fallback retained.
2. SigV4 (AWS_IAM) inbound by default; CUSTOM_JWT (Cognito M2M) only where a 3LO OAuth outbound target requires it (e.g. Linear).
3. Outbound auth branches by target type (execution role / SigV4 / API-key / OAuth 2LO / OAuth 3LO), all vaulted through AgentCore Identity.
4. Targets are registry-declared (relates to feat(registry): central agent asset registry for capabilities, skills, plugins, and MCP servers #246).

Governance note

Filing this ADR PR as the mechanism to move the #641 decision toward accepted. Issue #641 is not yet approved-labelled; implementation PRs (P1+) will follow ADR-003 governance once the decision lands.

Validation

• mise //docs:check — 0 errors (astro fix verified).

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.