ADR-070: MCP-Consumer Connector Architecture

Status: v0.1 (filed 2026-06-15) — Architect-authored; PM-ratified direction (2026-06-14: connectors move to MCP-consumer; staying native is “dated and clunky”); gates Lead Dev WS-1..9 decomposition on the RECONNECT sprint (#1220 umbrella + 12 issues). Amended: A (2026-07-10, logical server key) and B (2026-10-13, one credential resolver per connector).

Date: 2026-06-15

Authors: Chief Architect (Arch)

Reviewers: Lead Developer (RECONNECT sprint owner; #1220 anchor + 11 WS issues), PPM (milestone placement), CIO (methodology), CEO (xian — direction ratifier)


Status


Context

What problem does this ADR solve?

PM ratified (2026-06-14) that Piper’s connector model moves to MCP-consumer rather than native bespoke integrations. The ratification settled the direction; this ADR settles the how — specifically the four questions Lead Dev’s input doc identified as Arch’s lane:

  1. MCP-consumer substrate shape — what does the connector abstraction look like in MCP-consumer form?
  2. Auth ownership — how much of OAuth/token lifecycle moves to the MCP server vs. stays in Piper?
  3. Per-connector migration path — how does each native integration transition without breaking M3?
  4. MCP-server maturity per connector — sequencing input given uneven server maturity (GitHub/Calendar well-served; Slack/Notion gap analysis needed).

The trigger artifact is #1226 (M3 UAT silent-config-failure) — a data/github_preferences.json cwd-relative flat-file that returned “no open issues” for a repo with many. Pulling the thread surfaced the systemic shape (P1-P8 in the scope doc): cwd-fragile config storage, four-conventions credential model, fragile-with-dead-paths resolution, silent degradation, no unified connector abstraction.

Why this is architectural, not a per-connector patch

PM’s framing — “not our first attempt” at clean connector models — is the recurrence signal. The same family of failure mode that drove ADR-071 (content anchoring) drives this ADR (connector substrate): without a canonical pattern, each new connector or each new fix re-invents (or fails to invent) the discipline. Patching data/github_preferences.json to be DB-backed without a connector-wide contract just defers the next variant.

Format-decision space (inherits from existing ADRs)

Prior art / cross-references


Decision

The MCP-Consumer Connector Architecture is a unified Connector protocol (connect / status / resolve / degrade) implemented by MCP-consumer adapters + DB-backed user-scoped config (replacing cwd-relative flat files) + MCP-server-owned OAuth/token lifecycle (with Piper storing per-user MCP-server bindings, not raw credentials) + a maturity-tiered per-connector migration sequenced via m-40 layer-then-migrate. Native services/integrations/* retire as MCP-consumer adapters reach parity.

D1: Architectural shape — Piper as MCP consumer

Decision: Piper’s connector substrate is the existing services/mcp/consumer/*_adapter.py foundation. Native services/integrations/{connector}/ is deprecated; new connector work targets MCP-consumer adapters exclusively. The MCP-consumer protocol IS the connector abstraction (WS-5 = the MCP-consumer contract; not two separate things).

This is the PM-ratified direction, made concrete: the connector lane unifies on one substrate. The bifurcation that drove P8 in Lead’s scope doc (services/integrations/{connector}/ and services/mcp/consumer/*_adapter.py coexisting) ends with native retirement.

D2: ADR-052 reconciliation — two distinct boundaries

Decision: ADR-052’s tool-based MCP standardization applies to Piper-as-host (Piper exposing its own tools to MCP clients like Claude Desktop). ADR-070 applies to Piper-as-consumer (Piper consuming external tools/resources from MCP servers like github-mcp-server). These are two distinct boundaries, not in tension:

ADR Boundary Direction Owns
ADR-052 Piper-as-host Piper exposes tools to MCP clients (Claude Desktop, ChatGPT-MCP, etc.) Piper’s tool surface; tool-based standardization; no separate MCP servers in front of Piper
ADR-070 Piper-as-consumer Piper consumes tools/resources from external MCP servers The external server owns auth + the underlying resource; Piper stores bindings only

ADR-052’s “rejected separate MCP servers” applied to Piper’s tool surface (don’t fragment Piper’s API across multiple servers). It did not apply to consuming external servers. The ADRs compose cleanly.

D3: Auth ownership split — MCP server owns OAuth; Piper stores bindings only

Decision: The external MCP server (github-mcp-server, google-calendar-mcp-server, etc.) owns the connector’s OAuth flow, token storage, and token refresh lifecycle. Piper stores only:

Piper does not store:

This structurally eliminates the silent-config-failure class (#1226): if the binding exists and the MCP server is reachable, the connector is configured. The four-conventions credential model (P2) collapses to one convention: server-binding-by-user. The _api_key keychain foot-gun (CLAUDE.md) reduces to MCP-server-internal concerns, not Piper’s discipline.

Cross-reference: ADR-066 v0.2 D7 (Configuration Ownership) makes this the consistent posture across server-owned-config and server-owned-creds. ADR-058 (Multi-Tenancy Isolation) credential storage convention applies to Piper’s binding storage (per-user scoping per ADR-058).

D4: Config ownership — DB-backed, user-scoped (kills cwd-relative flat files)

Decision: All per-user connector configuration lives in Piper’s DB, user-scoped per ADR-058. The data/*_preferences.json flat files are retired by WS-1. The DB schema for connector config carries:

Cross-reference: ADR-066 D7 enforces this — host-filesystem persistence is forbidden; server-owned-DB is the canonical home. ADR-071 (Lead-authoring) D2/D3 invariants apply to read/write paths on this config (owner-stamped at write; principal-scoped at read).

D5: Connector abstraction — single protocol, four methods

Decision: One Connector protocol that all MCP-consumer adapters implement:

class Connector(Protocol):
    async def connect(self, user_id: str) -> ConnectResult: ...
    async def status(self, user_id: str) -> ConnectorStatus: ...
    async def resolve(self, user_id: str, resource: ResourceQuery) -> ResolveResult: ...
    async def degrade(self, reason: DegradationReason) -> DegradationResponse: ...

Guard pattern (m-41 mechanism-displaces-vigilance): an AST-level enforcement test asserts every MCP-consumer adapter implements all four methods. New connectors fail the build if they skip honest-degradation or status reporting. Same shape as TestSessionScopeCommitContract (#1193 / ADR-069 D5) and the m-41 cure-class generalization (CIO catalog 2026-06-13).

D6: MCP-server maturity tiers — sequenced migration

Decision: Per-connector migration sequenced by MCP-server maturity:

Tier Connectors Status Migration timing
Tier 1 GitHub, Google Calendar MCP server well-served; published; stable Migrate first (Phase 2-3)
Tier 2 Slack, Notion MCP server maturity needs assessment Gap analysis Phase 0; migrate Phase 3-4 if mature, else native-with-shim until mature
Tier 3 local_git, future connectors New connectors target MCP-consumer-only Default for new work

Tier-2 escape valve: if Slack/Notion MCP servers are insufficiently mature at the time of their migration window, hold native temporarily with an explicit TODO(adr-070-tier2): migrate when MCP server matures comment + a tracking issue. Do not block the rest of the migration on Slack/Notion; the Tier 1 + new work proceeds.

D7: Migration sequencing — layer-then-migrate per m-40

Decision: For each Tier 1 connector, m-40 layer-then-migrate:

  1. Layer: introduce MCP-consumer adapter alongside the existing native integration. Feature-flag the connector implementation choice per user.
  2. Migrate: opt-in users to MCP-consumer path; monitor honest-degradation surfaces for ConnectRequired rate (the new structurally-honest “not configured” signal).
  3. Collapse: once MCP-consumer path is healthy at parity (~weeks of monitoring), retire the native integration. Delete services/integrations/{connector}/.

Native retirement is the m-40 collapse step; the migration is not complete until the native code is removed. The is_global_pm_domain / is_legacy_native escape-hatch pattern from ADR-071 D6 inverts here: native integrations are the deprecated side, MCP-consumer is the canonical side; the marker is “is_native_legacy=true” on the bindings table during the transition.

D8: Identity unification (WS-9) ordering — prerequisite, not parallel

Decision: WS-9 (identity unification — the web a25db09c vs Slack 009afc8c finding) is a prerequisite for the connector migration, not a parallel workstream. Reasoning:

Cross-reference to ADR-071: identity unification IS the Architect-clarifying-question that surfaces for ADR-071 D7 multi-tenant migration too. Same shape (resolve identity first, anchor content second); ADR-070 D8 makes the identity-first ordering explicit at the connector boundary.

D9: ADR-058 finishing-the-job — not greenfield

Decision: This ADR explicitly frames much of RECONNECT (WS-2 / WS-7 / WS-9) as finishing ADR-058’s implementation, not greenfield. The audit cascade Lead Dev ran (5 agents, 2026-06-14) verified ADR-058 already settled:

WS-2 (#1229), WS-7 (#1109, #1110), WS-9 (#1233) cite ADR-058 as the governing decision rather than re-deriving conventions. The connector migration is completing ADR-058 across the bespoke-integration code paths that pre-dated or bypassed it. This avoids the re-litigation pattern PM named at the cohort-discipline layer.


Implementation sequencing (suggested for Lead Dev)

This refines the input doc’s Phase 0-3 with the D-section grounding:

Per-connector migration sequence (D6 tier-grounded)

Tier 1 first: GitHub (highest M3 value; MCP server mature) → Google Calendar (M4-relevant; mature). Tier 2 assessment Phase 0; tier 2 migration Phase 3-4 if mature.

The GitHub prefs-file band-aid (#1226-trigger M3 work-around) is not the WS-1 fix — it’s an explicit band-aid that gets deleted by WS-1 once the DB-backed config + GitHub MCP-consumer migration land. WS-1’s deletion of data/*_preferences.json is the m-40 collapse step.


Consequences

Positive

Negative / Tradeoffs

Non-consequences


Evolution

(Empty at v0.1 filing. Klatch-pause framing per Pattern-064 convention applies if cross-project relevance surfaces.)


Open questions (v0.1)

  1. MCP server selection per connector — Lead Dev consultation at WS-5 implementation. Initial lean: use Anthropic-published MCP servers where available (github-mcp-server, etc.); evaluate community + build-own at gap moments.
  2. WS-9 identity-unification scope — depends on whether web a25db09c and Slack 009afc8c are the same human (plausible-but-unproven per Lead’s audit). PM may need to disambiguate from outside the system. Filed as #1233 sub-question.
  3. D6 Tier 2 maturity assessment — Slack and Notion MCP server health survey. Lead Dev or PPM assigns when Phase 0 closes.
  4. D5 protocol formalization — ConnectResult / ConnectorStatus / ResolveResult / DegradationResponse types — Lead Dev defines at WS-5 (#1232) authoring; D5 here specifies the methods, not the parameter/return shapes in detail.
  5. D3 OAuth-state-on-Piper-side — does Piper retain any OAuth state (CSRF tokens, etc.) for the connect-flow handshake, or does the MCP server own all OAuth-state including the in-flight handshake? Initial lean: MCP server owns all of it; Piper’s connect() is purely a redirect-+-callback orchestrator. Lead Dev consultation at Phase 1.

What this ADR is NOT


Supersession note — the PM-033/034 MCP-era documents (recorded 2026-08-02, Arch)

This ADR supersedes the PM-033/034-era MCP architecture documents for the MCP-consumer connector concern:

Why this note exists rather than being left as an obvious inference: ruling on those files’ disposition during Docs’ 2026-08-01 architecture-tree audit, I reached for “superseded by ADR-070” — then checked, and found this ADR mentioned PM-033/034 exactly zero times. The supersession was my inference, not a recorded fact, and asserting an inference as a fact inside a durable record is precisely ADR-038 Amendment A §A3. So it’s recorded here, in the superseding document, where a future reader of either side can find it.

⚠️ scripts/setup_mcp_dev.sh:200 prints a path to pm-033a-mcp-consumer-architecture.md for users — and that path (docs/architecture/…) has already not resolved for some time; the file lives under docs/internal/architecture/current/. A user running setup is pointed at nothing today. The correct target is this ADR, not the archived original: someone setting up wants current architecture, not history. Flagged to Docs 2026-08-02; ownership of that script is not mine.


Amendment A (2026-07-10) — mcp_server_ref stores a logical key, not a topology (resolve at read-time)

Trigger: the #1278 Fly cutover silently invalidated PM’s GitHub binding — connector_bindings.mcp_server_ref stored the literal compose hostname (http://github-mcp:8082/mcp), pg_dump/restore carried it verbatim onto Fly where that host doesn’t exist, and the binding degraded to UNREACHABLE while reporting BOUND. The failure looked like a server outage, not a config problem. PM asked for a ruling before the #1232 port train mints more literal refs.

Root cause (category error): mcp_server_ref conflates which logical connector-server (a deployment-invariant identity) with where it lives right now (a deployment-variant topology). Pinning topology into a per-user binding row means every host/topology change silently invalidates bindings, and parallel environments (alpha + beta, live concurrently as of the cutover) cannot share a correct row — one is wrong by construction. Same class as the #1283 / Intent.original_message lesson one layer down: a value resolved once at write-time with N read-time consumers and no single read-time authority.

Ruling — Option B (env-resolved indirection), refining the D-ruling that placed the server ref on the binding:

Sequencing: not tonight; before the next connector port mints more rows (Lead). Both live environments have correct refs right now (alpha’s compose host; Fly’s .internal, repointed at cutover) — no runtime gate.

Amendment A — Chief Architect, 2026-07-10, on Lead’s PM-requested design question; Lead leaned B, Arch ruled B + the single-resolver-authority (A2) and honest-degrade (A4) conditions.


Amendment B (2026-10-13) — one credential resolver per connector; GitHub has two legs

Trigger: #1965 (Radar/standup work-items read) found two GitHub credential resolvers that disagreed: the adapter’s grant-aware path and the PAT-only GitHubConfigService.get_authentication_token. A user connected one way read as unconnected the other way, the #1547 false-clear shape. Arch ruled on 10-08 in mail and decisions.log; PPM’s Agent 360 v0.5 answer (8.3) asked whether it needs a PDR. It does not: it is a credential and status architecture rule, and it amends D3 below. This amendment is its durable home.

Ruling:

What this changes in D3. D3 says Piper stores bindings, not raw connector tokens. B2’s PAT leg is the one exception: a user’s own PAT, which they pasted into Settings, encrypted at rest under ADR-058’s per-user scoping. Piper does not mint, refresh or share it, and never substitutes a deployment token for it. OAuth tokens stay with the MCP server as D3 says.

Known edge, accepted, not handled: a BOUND binding whose grant is missing does not fall back to the PAT; it degrades at the call, as before #1965.

Verified how: read resolve_credential, _user_pat_at_rest and _user_pat in github_adapter.py on main at this commit; the order, the refusal of "system", the no-binding-row PAT leg and stale_oauth_reason all match B2–B3. Layer: source, not a served read. Denominator: the GitHub connector only; no other connector has a second leg today.

Amendment B — Chief Architect, 2026-10-13, recording the 10-08 #1965 (a)/(b) rulings (PA caught the missing PAT leg in the first one).


Decisions.log entry (per CLAUDE.md Recording-decisions discipline)

2026-06-15 — ADR-070 filed v0.1: Piper-as-MCP-consumer; one Connector protocol; MCP-server owns auth; Piper stores bindings only; DB-backed user-scoped config (kills flat files); tier-2 escape valve; identity unification (WS-9) is prerequisite to WS-1; finishes ADR-058 across native-integration paths. Unblocks RECONNECT WS-1..9 decomposition. Lead Dev: ratify or refine. — Arch

v0.1 — Chief Architect, 2026-06-15, from Lead Dev’s input doc. PM-ratified direction (2026-06-14); architectural how is this ADR.