docs: add MCP server guide and surface the OAuth entry point in the skill

[raulb]

Part of AI-1009

Are documentations specifically about withOAuthProtectedResource() in the context of using it for MCP servers, clarifying its usage with Supabase Edge Functions or not.

Note: I also updated the library components usage here supabase/supabase#50215 which will ship as part of supabase/supabase#49579.

[pkg-pr-new]

Open in StackBlitz

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

commit: 6595eab

[mandarini]

A few additions from running this on a real hosted Edge Function (diabuddy, @supabase/server 1.6.0, Deno 2.9). Each would fit in one sentence:

• Typed client for writes. withSupabase({ auth: 'user' }) without a generic gives SupabaseClient<unknown>. The sample only selects, but a tool that writes fails typecheck: insert({ title }) resolves the argument to never[]. Showing withSupabase<Database> (or <any>) in the sample avoids the first support question.
• Factory errors are invisible. An exception thrown inside the createMcpHandler factory (a duplicate tool name, a failed schema fetch) comes back as a 500 with nothing in the function logs. A try/catch with console.error in the factory is worth showing.
• OPTIONS on the metadata route. The entry also answers the preflight for {resource}/oauth-protected-resource with CORS headers. A third row in the table would document it for browser-based clients.
• The limits are the handler's, not the library's. The one-request, one-response shape comes from building a McpServer per request with createMcpHandler; @supabase/server does not constrain the transport. Saying so avoids the impression that the entries rule out a stateful transport.
• Root path without a slug. On a CLI older than 2.117 serving the function at /, derivation throws MISSING_RESOURCE_SERVER. One line here saves a support question.

Verified against 1.6.0: the inline-handler TS2345 reproduces exactly as described, and the (req, ctx) => handleMcp(req, ctx) form compiles.

[mandarini]

Checked the page against origin/main (1.6.0), the URL derivation in src/oauth-protected-resource/url.ts, and a hosted Edge Function running this stack. Three factual fixes inline. The additions worth considering are in a separate comment.

[raulb]

@mandarini thank you for the feedback! You were right on all three. I'm currently running tests following across the library blocks supabase/supabase#50215 and future docs supabase/supabase#50218, so I'm hoping to leave this PR ready for review today.