supabase / mcp / 29405443353

96%

push

github

fix: actionable error for wrong-org permission failures on database tools (#329)

## Problem

Authenticating to the wrong organization (e.g. selecting the wrong org
during OAuth login) makes database tools (`list_tables`, `execute_sql`,
migrations) fail with a bare:

> You do not have permission to perform this action

Nothing indicates that org selection is the cause — hard to debug for
users, and useless to the LLM driving the session.

Linear:
[AI-178](https://linear.app/supabase/issue/AI-178/improve-mcp-db-tool-error-for-wrong-organization-selection)

## Change

* New `assertProjectScopedSuccess(response, fallbackMessage, projectId)`
in `management-api/index.ts`: intercepts **403 only**, preserves the
upstream API message when present, and appends:

> Access to project '<ref>' was denied. If this project exists, your
access token may be scoped to a different organization: re-authenticate
with the MCP server and select the organization that owns this project.

  All non-403 errors fall through to the existing `assertSuccess`.
* Wired into the three database platform ops (`executeSql`,
`listMigrations`, `applyMigration`), which back `execute_sql`,
`list_tables`, `list_extensions`, `list_migrations`, and
`apply_migration`.
* Intentionally **not** applied to other endpoints
(billing/admin/project ops), where a 403 can mean plan or role
restrictions and org-selection advice would mislead. JSDoc on the helper
documents this.

Note: the target project's org can't be named in the message — with a
wrong-org token the project lookup itself returns 403, so the org is
unknowable. The message names the project ref and the likely cause
instead.

## Verification

All commands run from `packages/mcp-server-supabase`:

* TDD: started with two failing tool-level regression tests
(`execute_sql` and `list_tables` against an MSW 403 override on
`/v1/projects/:ref/database/query`), which surfaced the raw upstream
message (`You do not have permission to perform this act... (continued)

321 of 355 branches covered (90.42%)

Branch coverage included in aggregate %.

32 of 32 new or added lines in 2 files covered. (100.0%)

2764 of 2849 relevant lines covered (97.02%)

42.48 hits per line