Claude Code + Powabase

Example apps

Real apps, each from one prompt. Copy any of them and give it to Claude Code.

Where Claude Code keeps your keys

Claude Code has no secrets store of its own. The key lives wherever your app reads it, usually a gitignored .env that your server code loads as BASE_URL and API_KEY. The Service Role key belongs only in server-side files; anything Claude writes for the browser should use the Anon key. If you'd rather Claude never open that file, add Read(./.env) to the deny list in your Claude Code settings: your app still loads it at runtime, Claude just can't read it.

Claude Code example

// Server-only helper: the key comes from the environment, never the browser.
const BASE_URL = process.env.BASE_URL!;
const API_KEY = process.env.API_KEY!; // Service Role (Secret) Key

export async function searchDocs(kbId: string, query: string) {
  const res = await fetch(`${BASE_URL}/api/knowledge-bases/${kbId}/search`, {
    method: "POST",
    headers: {
      apikey: API_KEY,
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query, top_k: 5, retrieval_method: "hybrid" }),
  });
  if (!res.ok) throw new Error(`Powabase search failed: ${res.status}`);
  const { results } = await res.json();
  return results; // [{ score, text, ... }]
}

This is the shape Claude writes once the skill is installed: a server-side helper that searches a knowledge base with hybrid retrieval. Your route handlers call it; nothing in the browser sees the key.

Connecting to Powabase from any tool

Mechanics that don’t change from tool to tool.

• Every call to /api/* or /rest/v1/* needs two headers, apikey and Authorization: Bearer, both set to the same key. Sending only one is the most common cause of a 401.

  Docs↗

• The Database URL from the Connect modal is PgBouncer in transaction mode, not a direct Postgres connection. Disable prepared statements in your driver, or you'll hit prepared statement "..." does not exist. No LISTEN/NOTIFY and no session-level SET across statements. Use Realtime for change notifications; SET LOCAL inside a transaction otherwise. The username and database in the URL are both your project ref, not postgres.

  Docs↗

• @supabase/supabase-js mostly works for the BaaS surface (PostgREST, Auth, Storage, Realtime) when you point it at your project URL with the Anon key. It doesn't cover the /api/* AI surface (agents, knowledge bases, orchestrations), which you call over plain REST. There's no /graphql/v1 route: point any GraphQL client at POST /rest/v1/rpc/graphql instead.

  Docs↗

Common errors

Powabase is listed in /mcp, but Claude can't use any of its tools

Cause: The server was added, but the OAuth sign-in never finished, so Claude Code has no token for it.

Fix: Run /mcp, select powabase, and complete the browser sign-in. From a terminal, claude mcp login powabase does the same.

A teammate opens the repo and Claude Code has no Powabase server

Cause: claude mcp add writes to local scope unless told otherwise, and local scope is private to you.

Fix: Add it again with --scope project so it lands in .mcp.json, commit that file, and have each person sign in once.

401 Unauthorized

Cause: Only one of the apikey / Authorization headers was sent.

Fix: Send both, set to the same key. Docs↗

prepared statement "..." does not exist

Cause: PgBouncer's transaction-mode pooler moved you to a different server connection.

Fix: Disable prepared statements in your driver's config. Docs↗

A query that should return rows comes back empty, or a write is silently rejected

Cause: Row Level Security on your own tables. New public tables ship with RLS off, but once you add policies they gate every request.

Fix: Check the policy's USING/WITH CHECK clause and confirm which role (anon, authenticated, service_role) you actually authenticated as. Docs↗

The Service Role key turns up in a browser bundle or other client-visible code

Cause: It was used somewhere that ships to the client instead of staying server-side.

Fix: Move the call server-side; use the Anon key with RLS for anything client-visible. If it shipped, rotate it in Studio. Docs↗

FAQ