Supabase MCP shows connected in Claude Code but no tools load (Zod parse error)

Question

After connecting the Supabase MCP server in Claude Code (claude-code 2.1.126 on Windows and macOS), /mcp shows the server as connected but no tools register. A raw tools/list call via JSON-RPC returns: "Failed to parse Supabase Content API response" with an invalid_union Zod error. The same error appears on @supabase/mcp-server-supabase versions 0.6.0 through 0.8.0.

Originally asked on GitHub: https://github.com/supabase/mcp/issues/261

AgentArmorHQ team · Accepted Answer

This is fixed in `@supabase/mcp-server-supabase` v0.8.1 (released 2026-05-01). The cause was a Zod v3 to v4 breaking change: the server used `z.undefined()` in a union that expected either `{ errors: [...] }` or `{ data: ..., errors: undefined }`, but the Content API now returns successful responses with `data` and no `errors` key at all. In Zod v4, `z.undefined()` requires the key to be present, so an absent key fails validation.

**Fix**: upgrade. If you run the stdio server via `npx`, the maintainer confirmed that pointing the tag at `latest` picks up the fix.

**Workarounds** reported while waiting:

1. Pin the stdio server to `@supabase/mcp-server-supabase@0.5.10`, the last release before the Zod v4 bump. One commenter validated this against a 312-table production project; `tools/list` succeeded and `list_tables` returned rows.
2. Patch the cached dist file at `~/.npm/_npx/<hash>/node_modules/@supabase/mcp-server-supabase/dist/chunk-XLEPTKCS.js`, replacing `errors:g.undefined()` with `errors:g.optional(g.undefined())` and `data:g.undefined()` with `data:g.optional(g.undefined())` in the two schema objects. Multiple commenters confirmed this works, but it is lost on `npx --refresh`.

**Transport note**: the maintainer recommends the HTTP-based server instead of stdio. PATs are supported there via the Authorization header:

```json
{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SUPABASE_ACCESS_TOKEN}"
      }
    }
  }
}
```

*General advice: expand `${SUPABASE_ACCESS_TOKEN}` from an environment variable rather than hardcoding the token value into a committed config file.*

AgentArmorHQ team · Answer

**What @gregnr tried on GitHub** (Worked)

Maintainer merged the Zod schema fix in #269 and released it as v0.8.1, advising stdio users to use the `latest` tag; confirmed `latest` then worked.

Source: https://github.com/supabase/mcp/issues/261#issuecomment-4361455895

AgentArmorHQ team · Answer

**What @marinaldooliveira-creator tried on GitHub** (Worked)

Pinned the stdio server to @supabase/mcp-server-supabase@0.5.10 (pre-Zod-v4) with `npx -y ... --project-ref`; `tools/list` succeeded and all tools registered.

Source: https://github.com/supabase/mcp/issues/261#issuecomment-4361067839

AgentArmorHQ team · Answer

**What @jlognn tried on GitHub** (Worked)

Patched the cached dist file, replacing z.undefined() with z.optional(z.undefined()) in both schema branches of the parsed GraphQL response.

Source: https://github.com/supabase/mcp/issues/261#issuecomment-4357948403

AgentArmorHQ team · Answer

**What @darkcoder215 tried on GitHub** (Didn't work)

Reporter reinstalled Claude Code, removed access tokens, and deleted the setup entirely, on both Claude Code Web and Desktop.

Source: https://github.com/supabase/mcp/issues/261

Supabase MCP shows connected in Claude Code but no tools load (Zod parse error)

5 answers

Add your answer or comment

Supabase MCP shows connected in Claude Code but no tools load (Zod parse error)

5 answers

Add your answer or comment

Related questions