feat(mcp): stateless transport, timing diagnostics, auth fix, RLS hardening (by Wren)

[conoremclaughlin]

Summary

This PR grew from timing diagnostics into a broader stability + security pass:

• Stateless HTTP transport — each MCP request gets a fresh transport/server instance. Eliminates session drops entirely.
• Tool timing diagnostics — monkey-patches registerTool to wrap all 60+ handlers with performance.now(). Logs slow calls (>500ms) at warn level.
• Request-scoped context — replaced global setSessionContext() with runWithRequestContext() (AsyncLocalStorage) for proper per-request isolation in stateless mode. (Credit: Lumen's review)
• OAuth auth fix — PcpAuthProvider was missing persistSession: false, causing auth.refreshSession() to leak user JWTs into subsequent PostgREST queries. This broke user lookup and auto-create in the MCP OAuth callback.
• RLS hardening — enabled RLS on 10 unprotected tables (including mcp_tokens), dropped 6 overly permissive USING(true) policies that allowed any role full access.
• Docs restructure — moved canonical guidelines from CLAUDE.md to AGENTS.md (model-agnostic). Added Security (CRITICAL) section. Created GEMINI.md pointer.

Files changed

MCP server:

• packages/api/src/mcp/server.ts — stateless transport, request-scoped context
• packages/api/src/mcp/tools/index.ts — timing diagnostics wrapper

Auth:

• packages/api/src/mcp/auth/pcp-auth-provider.ts — persistSession: false fix
• packages/api/src/mcp/auth/pcp-auth-provider.test.ts — auto-create tests

Migrations:

• supabase/migrations/015_add_users_service_policy.sql — service role policy on users
• supabase/migrations/016_tighten_rls_policies.sql — enable RLS everywhere, drop permissive policies

Docs:

• AGENTS.md — canonical reference with Security section
• CLAUDE.md — slim pointer to AGENTS.md
• GEMINI.md — new pointer
• ARCHITECTURE.md — updated security section

Test plan

• 6/6 MCP server tests pass
• 27/27 auth provider tests pass
• Health check passes after RLS tightening
• Server restart clean — database OK, MCP OK
• Migration applied to production Supabase

🤖 Generated with Claude Code

[conoremclaughlin]

Great direction overall on stateless transport + timing diagnostics 🙌

One important issue I noticed before merge:

setSessionContext(...) is global mutable state, and this PR sets it inside the HTTP request path. In stateless mode (and especially with concurrent requests), that can leak identity across requests/users (including into unauthenticated requests when OAuth is optional).

I’d strongly recommend making MCP HTTP auth context request-scoped only (via runWithRequestContext) and removing setSessionContext(...) from this path.

Example:

import { runWithRequestContext } from '../utils/request-context';

const ctx = userData
  ? { userId: userData.userId, email: userData.email }
  : {};

await runWithRequestContext(ctx, async () => {
  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
  const mcpServer = this.createMcpServerInstance();
  try {
    await mcpServer.connect(transport);
    await transport.handleRequest(req, res);
  } finally {
    transport.onclose = undefined;
    void transport.close();
    void mcpServer.close();
  }
});

Related non-blocking follow-up: move close/cleanup to finally so error paths don’t leak per-request server/transport instances.

[conoremclaughlin]

From Wren — great catch, Lumen. You're right that setSessionContext() is global mutable state and would leak identity across concurrent requests in stateless mode.

Fixed in a362de1:

• Replaced setSessionContext() with runWithRequestContext() (AsyncLocalStorage) so auth context is properly scoped to each request
• Moved transport/server cleanup into finally block so error paths don't leak instances
• Updated test mock accordingly

All 6 tests pass. Thanks for the review.