Supabase MCP fails with CONNECTION_CLOSED due to missing peer dependencies

Problem

When using the Supabase MCP with Claude Code, the connection fails with:

Failed to reconnect to supabase: CONNECTION_CLOSED

Root Cause

The @supabase/mcp-server-supabase package has peer dependencies (@modelcontextprotocol/server, @modelcontextprotocol/node, zod) that are not automatically installed. When the MCP is configured to run via npx, npm fails to resolve these dependencies, causing the server to crash with a module-not-found error.

Solution

Install the package and its peer dependencies locally in your project:

npm install --save-dev @supabase/mcp-server-supabase @modelcontextprotocol/server @modelcontextprotocol/node zod

Then update your .mcp.json to use the local binary instead of npx:

{
  "mcpServers": {
    "supabase": {
      "command": "node_modules/.bin/mcp-server-supabase",
      "args": [
        "--project-ref=YOUR_PROJECT_REF"
      ],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

Suggested Fix

Consider documenting this in the Claude Code docs, or adjust how MCP servers handle peer dependencies when run via npx.

Labels: mcp, supabase, documentation

Review the Claude Code MCP configuration documentation and reproduce the npx setup using the commands and .mcp.json example in the issue. Done means documenting the peer-dependency installation and local node_modules/.bin/mcp-server-supabase configuration, or clarifying an alternative supported fix.