feat(branching): tell agents when the organization's plan has no branching

[Rodriguespn]

Refs AI-1292. Hiding the tools with tools/list_changed is AI-1294; project-scoped branch creation is AI-1297. Decision thread: Slack.

Before: about 21% of create_branch calls fail, mostly PaymentRequiredException: "Branching is supported only on the Pro plan or above" (1,409 in 7 days). Only create_branch hits it; the other branch tools had 0 such errors.

After: when the platform says the project's organization can't use branching, every branching tool (create_branch, list_branches, delete_branch, merge_branch, reset_branch, rebase_branch) and branch get_cost return that answer as a normal tool result instead of a tool error. Nothing else changes.

• BranchingOperations gains an optional getAvailability({ projectId } | { branchId }) (the host resolves a branch to its project) → { available: true } | { available: false; message?: string }. Without message, the server uses a generic one.
• create_branch asks before any cost step; list_branches asks with the project, and the branch-id tools ask with the branch, after the read-only check. The result carries the message in content and structuredContent: { status: 'unavailable', message }.
• get_cost gains an optional project_id (only when the host implements getAvailability) and asks for branch quotes. Added in server.ts, next to the existing get_cost/confirm_cost adjustments, so the account tools don't depend on branching.
• Project-scoped create_branch accepts a missing confirm_cost_id so it can reach the check; when branching is available it still fails with the existing "User must confirm understanding of costs before creating a branch." (see AI-1297).
• Hosts without getAvailability, and failed checks, keep today's behavior.

Platform: availability is decided by getBranchingAccess (entitlement, free-org allowlist, K8s projects). The platform adds GET /v1/projects/{ref}/branching → { available } and the hosted MCP's getAvailability (separate supabase/platform PR).

⚠️ dacdf83 is TEMPORARY: the stdio platform calls GET /v1/projects/{ref}/branching with a hand-written fetch, so the evals can run on the preview now. Replace it with the typed managementApiClient call once the endpoint is deployed and the generated types include it. Do not merge with it.

Verification:

• Regression: all 415 unit tests on main still pass by name, plus 14 new ones (429/429), with and without the TEMP commit; typecheck and biome clean.
• tools/list vs main: no tools added or removed; only get_cost gains optional project_id and project-scoped create_branch no longer requires confirm_cost_id.
• Evals (supabase/evals#375), local live run, codex-gpt-6-luna with and without skills, 3 runs each: 002 free 6/6, 004 free project-scoped 6/6, 003 Pro 3/6 (the 3 failures stop to ask the user to approve the price; single-turn harness limit). Zero tool errors in all 18 runs.

Expected conflicts: with #428/#455 in create_branch and server.ts; to re-check before merge.

AI disclosure: implemented with an AI agent (omp, Claude). Pedro Rodrigues is the accountable owner and reviews before merge.

[pkg-pr-new]

Open in StackBlitz

pnpm add https://pkg.pr.new/@supabase/mcp-server-postgrest@f34a9ba

pnpm add https://pkg.pr.new/@supabase/mcp-server-supabase@f34a9ba

pnpm add https://pkg.pr.new/@supabase/mcp-utils@f34a9ba

commit: f34a9ba

[coveralls]

Coverage Report for CI Build 37775658052

Coverage decreased (-0.1%) to 96.893%

Details

• Coverage decreased (-0.1%) from the base build.
• Patch coverage: 11 uncovered changes across 1 file (111 of 122 lines covered, 90.98%).
• No coverage regressions found.

Uncovered Changes

File	Changed	Covered	%
packages/mcp-server-supabase/src/platform/api-platform.ts	31	20	64.52%
Total (3 files)	122	111	90.98%

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	4592
Covered Lines:	4470
Line Coverage:	97.34%
Relevant Branches:	751
Covered Branches:	707
Branch Coverage:	94.14%
Branches in Coverage %:	Yes
Coverage Strength:	89.2 hits per line

---

💛 - Coveralls