Debugging the Supabase MCP Server: A Tale of 401s and Argument Parsing

So you want to use the Supabase MCP server in VS Code? Great choice! But if you’re here, you probably ran into some… issues. Let me walk you through the debugging journey I just went through, because this stuff is never as straightforward as it should be.

The Initial Setup (Spoiler: It Didn’t Work)

Started with what seemed like a reasonable configuration in settings.json:

"mcp.servers": {
  "supabase": {
    "command": "npx",
    "args": ["-y", "@supabase/mcp-server-supabase"],
    "env": {
      "SUPABASE_ACCESS_TOKEN": "sbp_3da3153b00262fe3403bbe87ad99a995e8c367aa"      
    }
  }
}

Error #1: The 401 OAuth Mystery

Fired it up and got hit with this:

Discovered resource metadata at https://mcp.supabase.com/.well-known/oauth-protected-resource/mcp
Using auth server metadata url: https://api.supabase.com
Discovered authorization server metadata at https://api.supabase.com/.well-known/oauth-authorization-server
Error getting token from server metadata: Canceled: Canceled
Connection state: Error 401 status sending message to https://mcp.supabase.com/mcp: {"message":"Unauthorized"}

The Problem: That configuration points to the HTTP version of the MCP server (https://mcp.supabase.com/mcp), which requires OAuth browser authentication. Just setting an access token in the environment doesn’t cut it.

The Fix: Switch to the stdio version in mcp.json instead, which runs the server locally via npx and accepts the access token directly.

Moving to stdio Mode (Still Not Done…)

Switched to mcp.json with the stdio configuration:

"com.supabase/mcp": {
  "type": "stdio",
  "command": "npx",
  "args": [
    "--project-ref",
    "${input:project-ref}",
    "--read-only",
    "${input:read-only}",
    "--features",
    "${input:features}",
    "--api-url",
    "${input:api-url}",
    "@supabase/mcp-server-supabase@0.6.2"  // <- THIS IS THE PROBLEM
  ],
  "env": {
    "SUPABASE_ACCESS_TOKEN": "${input:SUPABASE_ACCESS_TOKEN}"
  }
}

Error #2: NPM Thinks My Project ID is a Package

npm warn "rdcvydxmsyljrruandhr" is being parsed as a normal command line argument.
npm warn Unknown cli config "--project-ref". This will stop working in the next major version of npm.
npm error 404 Not Found - GET https://registry.npmjs.org/rdcvydxmsyljrruandhr

The Problem: The package name was at the END of the args array. NPM was interpreting --project-ref and my project ID as arguments to npx, then trying to install my project ID as an npm package. Yikes.

The Fix: Move the package name to the BEGINNING of the args array (right after the -y flag):

"args": [
  "-y",
  "@supabase/mcp-server-supabase@0.6.2",  // <- Package name FIRST
  "--project-ref",
  "${input:project-ref}",
  // ... other args
]

Almost There… But Not Quite

Started the server again with the fixed args order…

Error #3: The Empty Argument Problem

TypeError [ERR_PARSE_ARGS_INVALID_OPTION_VALUE]: Option '--features' argument is ambiguous.
Did you forget to specify the option argument for '--features'?
To specify an option argument starting with a dash use '--features=-XYZ'.

The Problem: The optional arguments (--read-only, --features, --api-url) were being prompted as inputs. When you don’t provide values (or provide empty values), the command line parser sees something like --features --api-url and freaks out because --features expects a value but gets another flag instead.

The Fix: Strip out all the optional arguments and only keep what’s actually required:

The Final, Working Configuration

Here’s what actually works:

mcp.json

{
  "inputs": [
    {
      "id": "project-ref",
      "type": "promptString",
      "description": "Supabase project reference ID",
      "password": false
    },
    {
      "id": "SUPABASE_ACCESS_TOKEN",
      "type": "promptString",
      "description": "Personal access token for Supabase API",
      "password": true
    }
  ],
  "servers": {
    "com.supabase/mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@0.6.2",
        "--project-ref",
        "${input:project-ref}"
      ],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "${input:SUPABASE_ACCESS_TOKEN}"
      },
      "gallery": "https://api.mcp.github.com",
      "version": "0.6.2"
    }
  }
}

That’s it. Clean, minimal, and actually works.

Key Takeaways

HTTP vs stdio: The HTTP version (https://mcp.supabase.com/mcp) requires OAuth. If you want to use a simple access token, go with the stdio version.
Package name placement matters: With npx, the package name must come FIRST in the args array, followed by its arguments. Otherwise npx tries to interpret your flags as its own.
Empty optional arguments break things: Node’s argument parser doesn’t handle empty optional arguments gracefully. If you’re using input prompts for optional flags, either provide default values or just remove them entirely.
Get your project reference ID: You can find this in your Supabase dashboard URL: https://supabase.com/dashboard/project/YOUR-PROJECT-REF
Personal access tokens: Generate one at https://supabase.com/dashboard/account/tokens

Actually Starting the Server

Once you’ve got the config in place:

Restart VS Code (or reload the window)
When prompted, enter your project reference ID
When prompted, enter your personal access token
The server should start without errors

And you’re good to go! Now you can actually use those sweet Supabase MCP tools in your Copilot chat.

Debugging is just a fancy word for “trying stuff until it works.” Hope this saves you some time!

Configuring Supabase MCP server

A Tale of 401s and Argument Parsing