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)
docs/internal/architecture/connector-refactor-sprint-scope-2026-06-14.md.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:
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.
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.
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.
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.
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.
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).
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:
user_id (FK per ADR-058 + ADR-071 D2 canonical owner_id FK convention)connector_type (enum: github, calendar, slack, notion, …)mcp_server_binding_id (FK to the server-binding registry — D5)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).
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: ...
connect initiates the user’s OAuth flow against the connector’s MCP server; returns a binding or a ConnectRequired honest-degradation response.status reports the binding’s current health (bound / unbound / unreachable / stale-token-needs-refresh) without performing a resource fetch.resolve maps a resource query (e.g., “the user’s default GitHub repo”) to a concrete resource handle via the bound MCP server.degrade is the honest-degradation contract: returns "connect me" for unbound, "resource not found" for resolve-misses, etc. Never silently empty; this is WS-4 made structural.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).
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.
Decision: For each Tier 1 connector, m-40 layer-then-migrate:
ConnectRequired rate (the new structurally-honest “not configured” signal).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.
Decision: WS-9 (identity unification — the web a25db09c vs Slack 009afc8c finding) is a prerequisite for the connector migration, not a parallel workstream. Reasoning:
user_ids in Piper, MCP-server bindings fragment across both records, and the user experiences “I connected GitHub” but Slack-side Piper says “GitHub not connected.”owner_id FK target) → WS-2 (credential model; collapses to server-binding storage per D3) → WS-5 (abstraction; once stores are aligned). WS-3 + WS-4 can interleave with WS-5.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.
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.
This refines the input doc’s Phase 0-3 with the D-section grounding:
degrade() method) + WS-5 (#1232) (Connector protocol per D5).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.
_api_key keychain foot-gun becomes MCP-server-internal not Piper’s discipline.status() returns granular health states; D5 degrade() surfaces honest reasons. Cannot eliminate the externalization entirely.a25db09c vs Slack 009afc8c finding may turn out to NOT be the same human (Lead’s audit notes this is plausible-but-unproven). If they’re distinct identities, the WS-9 scope shifts from “merge records” to “support multi-identity per human at the connector layer.” D8 ordering holds either way.⚠️ STALE POINTER, corrected 2026-08-01 (Arch). M4 and M5 were SWEPT 2026-07-04/05 (
docs/internal/planning/beta-blockers.md); everything that missed the beta hard-gate bar moved to Production. So the sprint options named above — here and at lines 18 and 179 — point at sprints that no longer exist. The deferral itself still stands (placement is PPM’s), but do not read “M4 or M5” as live guidance; re-derive placement from the current sprint set.✅ PLACEMENT ANSWERED 2026-08-01 (PPM), and it needed no new decision — PM had already ruled it.
decisions.log2026-07-16 ~18:05 PT (Lead, PM-stated in conversation): “PRODUCTION (1.0) GATE: four core connectors — GitHub, Google Calendar, Slack, Notion — must be fully refactored/completed (besides the LLM) to close the Production milestone. Beta explicitly authorized to START without them; completion happens DURING beta.” ADR-070 is the MCP-consumer connector architecture for those four, so the full migration is Production-milestone work and beta starts without it — consistent withbeta-blockers.mdand roadmap v18.4. The ADR’s deferral-to-PPM is therefore discharged by a ruling that predates the question; the answer replaces the deferral rather than restating it.Found by a second-pass sweep of the ADR corpus for the ADR-038 Amendment A §A3 class — a durable document carrying a fact with a shorter lifetime than the document. My first sweep (7/30) checked only cold-module citations and “100% operational” phrasing and reported the blast radius as exactly one ADR; that was a partial sweep of its own space, which is the class it was checking for. Sprint names are perishable referents and belong in the same category as implementation citations.
github-mcp-server (Anthropic’s), community alternatives, or building Piper’s own are choices for Lead Dev at implementation time. The ADR specifies the architectural shape; the specific server is a downstream decision.(Empty at v0.1 filing. Klatch-pause framing per Pattern-064 convention applies if cross-project relevance surfaces.)
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.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.connect() is purely a redirect-+-callback orchestrator. Lead Dev consultation at Phase 1.This ADR supersedes the PM-033/034-era MCP architecture documents for the MCP-consumer connector concern:
pm-033a-mcp-consumer-architecture.mdpm034-deployment-guide.mdmcp-integration-points.mdmcp-integration-mapping.mdWhy 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.
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:
mcp_server_ref holds github (deployment-invariant); the URL resolves from deployment config at connect time (GITHUB_MCP_SERVER_URL already exists and is env-correct per-deployment — github_oauth_handler.py:37). Topology becomes a deployment property; a host move is a config change, not a per-row invalidation. Drift is impossible-by-construction for managed connectors (the make-drift-impossible spine — same move as ADR-077 derive-the-prompt / #1312 autogen-empty).resolve_server_ref(ref) -> url function is the sole authority; every read-site (github_adapter, google_calendar_adapter, the oauth_handler) routes through it. This is the load-bearing condition — B’s value is lost if the resolve logic scatters (the #1283 discipline: one resolver, not N consumers each parsing the value). The bind-time server_ref or _DEFAULT_MCP_SERVER_URL capture (github_oauth_handler.py:223) moves to read-time resolution.http(s)://…, stdio://…) is a literal self-managed / BYOC override; a bare token is a logical key. This preserves this ADR’s deliberate per-user-server intent (PDR-005 BYOC). Caveat, accepted: a BYOC literal can still go stale — but that URL names the user’s own server, whose lifecycle they own (semantically distinct from us moving our infra); re-bind is the honest recovery. The shape-contract lives in the resolver (A2), not as incidental parses at read sites.ResolveMiss (#1232) → CONNECT_REQUIRED-shaped honest degrade (D5), never silent-empty or crash. The incident’s tell was that the degrade looked like an outage; the degrade message must name the missing config, not read as a server being down.mcp_server_binding_id FK-to-registry: the logical key is the near-term realization; a first-class server-binding registry keyed by logical name, resolved per-deployment, is the fuller end-state when per-user server registries land. Optional lint: no managed-connector binding stores a scheme-prefixed ref (the BYOC exception is the only one, and it is explicit).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.
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:
GitHubMCPSpatialAdapter.resolve_credential (services/mcp/consumer/github_adapter.py). A second resolver is not taught the first one’s rules to keep them in sync; its callers move onto the one resolver (#1966 tracks the remaining get_authentication_token callers).user_api_keys row first, then the keychain path) → the PAT leg; (3) else an honest degrade: no binding → CONNECT_REQUIRED, a non-BOUND binding → its mapped reason. Never the env/system token for a real user (#1812, #1461); "system" and empty user ids are refused outright.stale_oauth_reason, so Settings can show the stale leg. Transport may differ per leg; leg choice stays in the resolver.DegradationReason (CONNECT_REQUIRED / STALE_TOKEN / UNREACHABLE / MISCONFIGURED) on the SOURCE_FAILED record, so the user sees “connect GitHub” or “couldn’t reach GitHub”, not an empty list. Copy is CXO’s (accepted 10-08).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).
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.