feat(mcp-server): resolve memberships from the server (MCP Prompt 08b)

[gilgardosh]

Summary

Implements Prompt 08b — MCP: resolve memberships from the server
(see docs/mcp/implementation-blueprint.md and docs/mcp/spec.md §6.4, §7.1).

The connector never derives business memberships from token claims. It resolves the caller's businesses by forwarding the user's bearer token to the Accounter GraphQL server and reading them back from the dedicated myMemberships query (added server-side in Prompt 08a, #4050). Because the connector holds a real end-user token, "authenticating to the server" is plain token pass-through — no Auth0 custom claim and no shared service secret.

Baseline note. 08b reuses the upstream client (createReadOperation / UpstreamGraphQLClient / getUpstreamClient) and the identity seam (resolveAuthContext, coerceMembership, membershipsFromClaims), none of which exist on mcp-setup/08a. This PR therefore targets claude/mcp-prompt-12-graphql-client (which stacks Prompts 09→12 on mcp-setup) — the earliest branch containing every seam it wires into. The diff below is only the 08b change.

Changes

• upstream/memberships.ts (new) — an upstream MembershipSource:
  • MY_MEMBERSHIPS_QUERY + a typed, read-only createReadOperation wrapper that maps myMemberships rows to the internal BusinessMembership shape via the shared coerceMembership.
  • createUpstreamMembershipSource({ client, authorization, correlationId }) returns a MembershipSource that forwards the caller's Authorization header and correlation id. Identity is carried by the forwarded token, so the principal isn't consulted.
  • Error semantics: any upstream/auth/infra failure throws (surfaces as 401/5xx) so a failed lookup never degrades into a silent empty scope. A genuinely empty server result maps to []. A non-list payload violates the server's non-null [MyBusinessMembership!]! contract and is treated as an upstream error.
• auth/identity.ts — export coerceMembership so the upstream source maps rows the same way the claims source does. The MembershipSource seam stays pluggable and membershipsFromClaims remains exported for tests.
• mcp/handler.ts — authenticate now builds the upstream source (getUpstreamClient() + the request's Authorization header + correlation id) and passes it to resolveAuthContext, replacing the default claims source. The token is never logged. Scoped the route's header comment now that the auth path makes one upstream call.
• Tests
  • upstream/__tests__/memberships.test.ts (new) — success maps rows to the internal shape (dropping businessName); forwards auth header + correlation id and issues myMemberships; empty result ⇒ []; malformed rows dropped; non-list ⇒ throws; upstream failure propagates.
  • mcp/__tests__/handler.test.ts — stub the membership source + upstream client accessor so the existing transport tests stay hermetic (no network / no upstream env required).

Precheck (per the prompt)

The forwarded token authenticates to the server only if the server accepts the MCP's Auth0 audience. This can't be exercised in CI (no live Auth0). Before enabling in a live environment, verify a real user token against an existing @requiresAuth server query; if the audiences differ, add a token-acquisition step (shared audience or Auth0 token-exchange) before wiring. Called out in the source docs.

Validation

• yarn workspace @accounter/mcp-server build (tsc) — passes.
• vitest --project unit packages/mcp-server — 150/150 pass.
• eslint clean on the changed source files; prettier formatted.

🤖 Generated with Claude Code

---

Generated by Claude Code

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[Copilot]

⚠️ Not ready to approve

The new upstream membership mapper can throw an unsanitized TypeError if the upstream returns data: null, bypassing the intended UpstreamError semantics.

Pull request overview

Adds an upstream-backed membership resolution path to the MCP server so business memberships are resolved from the Accounter GraphQL server (myMemberships) via bearer-token pass-through, rather than derived from token claims, and wires that source into request authentication.

Changes:

• Introduces an upstream MembershipSource (createUpstreamMembershipSource) that calls myMemberships and maps rows via the shared coerceMembership.
• Updates MCP auth flow to use the upstream membership source during authenticate (forwarding Authorization + correlation id).
• Adds unit tests for the upstream membership source and stubs upstream access in existing MCP transport tests to keep them hermetic.

File summaries

File	Description
packages/mcp-server/src/upstream/memberships.ts	New upstream membership source + myMemberships read operation wrapper and mapping logic.
packages/mcp-server/src/upstream/tests/memberships.test.ts	New unit coverage for mapping, forwarding context, empty/malformed payloads, and error propagation.
packages/mcp-server/src/mcp/handler.ts	Auth now builds and passes an upstream membership source to resolveAuthContext.
packages/mcp-server/src/mcp/tests/handler.test.ts	Mocks upstream membership source/client accessor to avoid network/env coupling in transport tests.
packages/mcp-server/src/auth/identity.ts	Exports coerceMembership for reuse by the upstream membership source.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 2
• Review effort level: Low

Note

Your feedback helps us improve the quality of this feature.
Please use 👍 or 👎 to tell us whether this assessment is correct.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.