MCP proxy Phase 0: compliance & compatibility spike (hosted endpoint contract, App tokens)

[chaodu-agent]

Part of #15 (Revision 2 added this phase from community review). Blocks the Phase 2 gate (#17).

Goal

De-risk the two external dependencies before building Phase 2: the hosted MCP endpoint's contract, and GitHub App installation tokens as the credential backend.

Tasks

• Resolve PAT-pooling compliance concern → decision: GitHub App installation token as primary credential (RFC Revision 2, Credential Architecture section)
• Verify hosted MCP endpoint contract (api.githubcopilot.com/mcp/):
  • GitHub App installation token accepted for auth? → YES (see findings comment)
  • Tool configuration timing → honored per-request; bonus: X-MCP-Tools exact per-tool allowlist exists (see findings)
  • Session lifecycle (partial) → upstream DELETE is a no-op (session reusable after 204!); unknown session → 400 upstream. ghpool's local pin cache is the real session authority. SSE resumption + server-side expiry still unprobed
  • Rate-limit headers → none; x-github-request-id present
  • Invalid toolset names → silently ignored, fail-open (full tool set!) — ghpool must use exact X-MCP-Tools allowlists
  • Timeouts, mid-stream disconnects, and credential-expiry-mid-session behavior
  • Protocol-version compatibility → 2024-11-05 accepted and negotiated
• Build automated contract test suite (extend scripts/e2e-mcp.sh / e2e workflow into scheduled runs — upstream is outside our release control)
• Define rollback/fallback path if upstream changes (self-hosted github-mcp-server container evaluation)

Deliverable

A findings doc (comment on this issue) + contract tests merged. #17 implementation starts only after the installation-token and session-lifecycle questions are answered.

[chaodu-agent]

Phase 0 spike findings

Probes run in CI (runs 29207381524 + follow-up on branch spike/mcp-contract, script scripts/mcp-contract-probe.sh) against api.githubcopilot.com/mcp/ with both a GitHub App installation token (minted from APP_ID/APP_PRIVATE_KEY) and a user PAT baseline.

🎯 The critical unknown: RESOLVED

GitHub App installation tokens are accepted — initialize returns 200 + session, full tool flow works. The Revision 2 credential architecture (#17) is viable as designed.

Findings table

#	Question	Answer	Impact on #17
A	App installation token auth	✅ accepted (HTTP 200)	App backend viable
B	Rate-limit headers	❌ none exposed; x-github-request-id present	budget accounting stays REST-driven; log request-id for support
C	Tool surface by credential	App token: 41 tools, user PAT: 44	tool surface varies with App permissions — policy must not assume a fixed set; grant App the right repo permissions
D/E	Toolset header timing	honored PER-REQUEST, not fixed at init (same session: no header→41, X-MCP-Toolsets: issues→9)	ghpool must inject policy headers on every request (it does); Revision 2's strip-client-X-MCP-* mandate is load-bearing — a client-supplied header would widen access mid-session
F	Invalid toolset name	⚠️ silently ignored — X-MCP-Toolsets: bogus_toolset_xyz → 200, full 41 tools	fail-open upstream! a config typo = full access. ghpool must validate toolset names, or better: use X-MCP-Tools exact allowlist (see K)
G	Readonly: header vs URL	/mcp/readonly URL variant: 24 tools (clearly restricted). X-MCP-Readonly: true on a single request didn't change tools/list count — inconclusive per-request	prefer the URL variant and/or exact tool allowlists for read-only enforcement
H	Old protocol version	2024-11-05 accepted and negotiated	no client-compat concern
I	Session termination	⚠️ DELETE → 204 but session still usable afterwards (reuse → 200)	upstream DELETE is effectively a no-op; ghpool's local unpin (→404) is the real termination boundary. Our Phase 1 behavior is already correct — and necessary
J	Unknown session upstream	HTTP 400 (spec says 404)	ghpool is the session authority and returns spec-correct 404 before upstream is reached; harmless divergence
K	Undocumented headers (from CORS allow-list)	🎁 X-MCP-Tools: a,b = exact per-tool allowlist (verified: 2 tools); X-MCP-Exclude-Tools works too; also advertised: X-MCP-Features, X-MCP-Lockdown, X-MCP-Insiders (unprobed)	#17's per-tool allowlist gets native upstream enforcement: ghpool policy (authoritative) + injected X-MCP-Tools (defense in depth). No reliance on coarse toolsets

Consequences for #17 design

1. Use X-MCP-Tools (exact allowlist), not X-MCP-Toolsets (categories) as the injected upstream filter — it matches the default-deny per-tool policy exactly and avoids the fail-open typo hazard (F).
2. Per-request header semantics (D) mean session-to-agent binding matters even more: policy is enforceable per request without re-initialization.
3. Upstream DELETE being a no-op (I) means ghpool's session cache is the single source of session truth — credential/session revocation (Phase 2 gate) is entirely ghpool's job.
4. App permissions determine tool surface (C) — document required App permission set as part of MCP proxy Phase 2 gate: agent authn + default-deny policy + GitHub App backend + writes #17.

Remaining #22 items

• Probe X-MCP-Lockdown / X-MCP-Features / X-MCP-Insiders semantics
• Credential-expiry-mid-session behavior (needs a token near expiry — test with a short-lived installation token)
• SSE resumption via GET + Last-Event-ID
• Convert the probe script into the scheduled contract test suite
• Rollback/fallback evaluation (self-hosted github-mcp-server)

Also noted: the e2e workflow (#21) could mint its token from the App secrets via actions/create-github-app-token and drop the E2E_GHPOOL_PAT PAT dependency entirely, now that App tokens are proven to work.