MCP (Model Context Protocol): Setup, Usage & Debugging

Overview

MCP connects AI coding agents (OpenCode, Claude Code, Cursor, etc.) to external services like Supabase, giving the agent direct access to tools such as running SQL, deploying edge functions, checking logs, and managing projects: all from within the conversation.

This project uses the Supabase Remote MCP Server scoped to a single project.

---

Configuration

Where the config lives

File	Purpose
.ai-agent-configs/opencode-xdg/opencode/opencode.jsonc	Main OpenCode config (read via XDG_CONFIG_HOME)
opencode.jsonc (project root)	Needed for opencode mcp auth CLI command to find the server

Config block

{
  "mcp": {
    "supabase": {
      "type": "remote",
      "url": "https://mcp.supabase.com/mcp?project_ref=vsfajebxloenaertaten",
      "enabled": true
    }
  }
}

URL parameters

Parameter	Description	Example
project_ref	Scopes to a specific Supabase project	?project_ref=vsfajebxloenaertaten
read_only	Execute all queries as read-only user	?read_only=true
features	Enable only specific tool groups	?features=database,docs

Parameters can be combined: ?project_ref=abc123&read_only=true

---

Authentication

First-time setup

1. Ensure the MCP config exists in opencode.jsonc at the project root
2. Open a separate terminal (not the OpenCode session):

   opencode mcp auth supabase

3. A browser window opens: log in to your Supabase account
4. Grant access to the organization containing the project
5. You'll see: Authentication successful!

Verifying connection

opencode mcp list

Expected output:

┌  MCP Servers
│
●  ✓ supabase connected
│      https://mcp.supabase.com/mcp?project_ref=vsfajebxloenaertaten
│
└  1 server(s)

Token storage

OAuth tokens are stored at: ~/.local/share/opencode/mcp-auth.json

Re-authentication

If the token expires or you get auth errors:

opencode mcp auth supabase

---

Available Tools

Once connected, the AI agent has access to these tools:

Database

Tool	Description
execute_sql	Run arbitrary SQL queries
list_tables	List all tables in specified schemas
list_extensions	List available/installed Postgres extensions
list_migrations	List database migrations
apply_migration	Apply a new migration

Edge Functions

Tool	Description
list_edge_functions	List all deployed edge functions
get_edge_function	Get source code of a specific function
deploy_edge_function	Deploy or update an edge function

Debugging

Tool	Description
get_logs	Retrieve service logs (API, Postgres, Edge Functions, Auth, Storage, Realtime)
get_advisors	Get security and performance recommendations

Development

Tool	Description
get_project_url	Get the API URL for the project
get_publishable_keys	Get anon/public keys
generate_typescript_types	Generate TypeScript types from schema

Docs

Tool	Description
search_docs	Search Supabase documentation via GraphQL

Branching (paid plans)

Tool	Description
create_branch / list_branches / delete_branch	Branch management
merge_branch / reset_branch / rebase_branch	Branch operations

---

Usage Examples

Running SQL

Ask the agent:

"What tables exist in the public schema?"

The agent calls list_tables or execute_sql with:

SELECT table_name FROM information_schema.tables WHERE table_schema = 'public';

Deploying an Edge Function

Ask the agent:

"Deploy the run-playground edge function"

The agent reads the source file and calls deploy_edge_function with the file contents, entrypoint, and JWT verification settings.

Checking Security

Ask the agent:

"Run the security advisors"

The agent calls get_advisors with type "security" and reports any warnings or issues.

Getting Logs

Ask the agent:

"Show me recent auth logs"

The agent calls get_logs with service "auth" and returns the last 24 hours of auth-related log entries.

---

Debugging Common Issues

"No OAuth-capable MCP servers configured"

Cause: The opencode mcp auth command can't find the config.

Fix: Ensure opencode.jsonc exists at the project root (not just in the XDG path). The CLI auth subcommand reads from the project root.

# Check it exists
Test-Path opencode.jsonc

MCP tools not available in session

Cause: The OpenCode session was started before the MCP was configured.

Fix: Restart the OpenCode session. MCP tools are loaded at session start.

"401 Unauthorized" from MCP server

Cause: OAuth token expired or was revoked.

Fix:

opencode mcp auth supabase

Tools return empty results

Cause: The MCP is scoped to a project that doesn't have the expected tables/functions.

Fix: Verify the project_ref in the URL matches your target project. Check in the Supabase dashboard.

"Invalid API key" when testing endpoints manually

Cause: The project was recreated or keys were rotated.

Fix: Use get_publishable_keys via MCP to get the current anon key:

Ask the agent: "What are the current publishable keys?"

Edge function deployment fails

Cause: Usually a syntax error in the function code or missing deno.json.

Fix: Always include both index.ts and deno.json in the deployment files. Check get_logs with service "edge-function" for runtime errors.

Connection timeout

Cause: Network issues or Supabase MCP server is down.

Fix: Test reachability:

$r = Invoke-WebRequest -Uri "https://mcp.supabase.com/mcp" -Method GET -UseBasicParsing
$r.StatusCode  # 401 = server is up (expected without auth)

---

Security Best Practices

1. Don't connect to production: Use MCP with development projects only. LLMs can execute destructive queries.
2. Use read-only mode for sensitive data: Add ?read_only=true to the URL.
3. Project scoping: Always include project_ref to prevent access to other projects.
4. Review tool calls: Most MCP clients show tool calls before execution. Always review SQL queries before approving.
5. Rotate secrets: If secrets were exposed in a session, rotate them immediately via the Supabase dashboard.
6. Never expose service_role key: Only publishable/anon keys should be in client code.

---

Architecture

The agent communicates with the remote MCP server over HTTPS. The MCP server acts as a proxy to your Supabase project, executing operations on your behalf using the OAuth credentials established during setup.

---

Adding More MCP Servers

You can add additional MCP servers alongside Supabase:

{
  "mcp": {
    "supabase": {
      "type": "remote",
      "url": "https://mcp.supabase.com/mcp?project_ref=vsfajebxloenaertaten",
      "enabled": true
    },
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    },
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

Local MCP servers

For custom tools or local-only services:

{
  "mcp": {
    "my-local-tool": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_API_KEY": "..."
      }
    }
  }
}

---

Per-Agent Tool Control

If MCP tools add too much context, disable them globally and enable per-agent:

{
  "mcp": {
    "supabase": {
      "type": "remote",
      "url": "https://mcp.supabase.com/mcp?project_ref=vsfajebxloenaertaten",
      "enabled": true
    }
  },
  "tools": {
    "supabase_*": false
  },
  "agent": {
    "db-agent": {
      "tools": {
        "supabase_*": true
      }
    }
  }
}

---

Session Log: Initial Setup (2026-06-07)

For reference, here's what was done during the first MCP setup:

1. Added mcp.supabase block to opencode.jsonc (both XDG and root)
2. Ran opencode mcp auth supabase in a separate terminal
3. First attempt failed ("No OAuth-capable MCP servers configured") because the root opencode.jsonc didn't exist yet
4. Created root opencode.jsonc, re-ran auth: succeeded
5. Verified with opencode mcp list: connected
6. Tested tools: get_publishable_keys, list_edge_functions, execute_sql all working
7. Deployed 3 edge functions via deploy_edge_function
8. Verified anonymous sign-in via the publishable key

---

External references

• OpenCode MCP docs (MCP servers section)
• Supabase MCP docs