feat(mcp): add @supabase/server/mcp

[raulb]

Try it out

npm i @supabase/server@1.7.0-beta.0

---

What kind of change does this PR introduce?

Bug fix, feature, docs update, ...

What is the current behavior?

Please link any relevant issues here.

What is the new behavior?

Feel free to include screenshots if it includes visual changes.

Additional context

Fixes AI-1173

Testing here

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@supabase/server@146

commit: 25e3be9

[mandarini]

Tried generateTools from 1.7.0-beta.0 in a hosted Edge Function (pipeline([withOAuthProtectedResource(), withSupabase({ auth: 'user' }), withPostgresClient()]), Claude Code as the client). Two things:

Hosted platform gates the OpenAPI root to secret keys

• GET /rest/v1/ with a publishable apikey returns 401 {"message":"Secret API key required","hint":"Only secret API keys can be used for this endpoint."}. Decided by the apikey alone; a user JWT in Authorization makes no difference.
• So generateTools(ctx.supabase) throws SPEC_FETCH_FAILED on every request on hosted Supabase. The caller-scoped client can never read the description there.
• Fix needed: let the description come from somewhere other than the client that executes the tools, e.g. generateTools(supabase, { describeWith: supabaseAdmin }) or generateTools(supabase, { spec }). Handlers keep running on the RLS-scoped client.
• Workaround I'm running: a facade { from, rpc, getOpenApiSpec: () => admin.getOpenApiSpec() } passed to generateTools. Works, but relies on those three being the only members touched.
• Consequence worth documenting: the admin description lists every verb of every table and every RPC the service role can execute, so callers will want to filter _meta.kind === 'function' and rely on RLS/grants at call time.

Name collisions with hand-written tools

• A hand-written list_daily_metrics next to table daily_metrics throws Tool list_daily_metrics is already registered inside the createMcpHandler factory → 500 with nothing in the logs.
• The docs already say to delete the generated entry first. A registerTools(server, tools, { skipExisting: true }) or a names/except option would make that the default path rather than a runtime crash.

Everything else worked as described: _meta filtering, COMMENT ON descriptions, fromJsonSchema argument validation, RLS at call time.

[mandarini]

Three more from the same dogfooding run, so this thread carries the complete list when the PR is picked up again:

• Errors thrown inside the createMcpHandler factory are invisible. Both failures above surfaced as a 500 with only boot/shutdown lines in the function logs; finding them took the Management API logs endpoint plus a fixture that patches McpServer.prototype.registerTool. Worth a paragraph in docs/mcp.md on surfacing ToolGenerationError (a try/catch with console.error in the factory), and it is a second argument for registerTools not throwing on a duplicate name.
• generateTools fetches the OpenAPI description on every call. In an Edge Function that is one GET /rest/v1/ per MCP message, on top of the secret-key requirement above. Accepting a pre-fetched spec or memoizing per isolate would pair naturally with the describeWith ask.
• Generation exposes whatever the project scaffold left behind. public.rls_auto_enable() is a SECURITY DEFINER helper the scaffold creates, executable by anon and authenticated; with the admin-described spec it became a tool until _meta.kind === 'function' was dropped. supabase db advisors --linked --type security flags it. A line in docs/mcp.md saying "run the security advisor before exposing generated tools" would save the next person the surprise.

Full write-up: https://linear.app/supabase/document/findings-from-dogfooding-ce88c7499028 (items 9, 12, 14).