feat(mcp): add `supabase mcp init` command to configure MCP clients #4383

Rodriguespn · 2025-10-29T15:30:59Z

What

Implements supabase mcp init and adds --mcp-client flag to supabase init to help users configure Model Context Protocol (MCP) clients to work with Supabase's remote MCP server.

Why

Closes https://linear.app/supabase/issue/AI-81
Addresses review feedback to attach MCP configuration to supabase init.

Users need an easy way to set up MCP integration with their preferred AI coding assistants without manually editing JSON configuration files.

How

Features

Interactive client detection: Automatically detects installed MCP clients on the system
3 supported clients: Claude Code, Cursor, and VS Code (with architecture for easy addition of more)
--mcp-client flag on supabase init: Target specific client for configuration
- Example: supabase init --mcp-client=claude-code
Remote server setup: Configures production server at https://mcp.supabase.com/mcp
Auto-configuration:
- Claude Code: Uses claude mcp add CLI command
- Cursor: Creates/updates .cursor/mcp.json with server URL
- VS Code: Creates/updates .vscode/mcp.json with server config (type: http)
Installation validation: Checks for actual binary/app presence before attempting configuration
Project-local & global configs: Supports both workspace and user-level configurations
Config merging: Intelligently merges with existing MCP configurations

Architecture

Built with scalability in mind:

Client interface: Defines contract for all MCP clients
Base client: Provides common functionality via composition
Separate files: Each client implementation in its own file
Easy extensibility: Add new clients by creating a file and registering in clientRegistry

Client-Specific Configurations

Claude Code

claude mcp add --transport http supabase https://mcp.supabase.com/mcp

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "supabase": {
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

Usage Examples

# Configure MCP during project init (addresses review feedback)
supabase init --mcp-client=claude-code

# Interactive mode - detects installed clients and configures automatically
supabase mcp init

# Target specific client via the dedicated command (still available)
supabase mcp init --client claude-code
supabase mcp init --client cursor
supabase mcp init --client vscode

# See all supported clients
supabase mcp init --help

Pull Request Test Coverage Report for Build 19105505226

Details

0 of 309 (0.0%) changed or added relevant lines in 9 files are covered.
5 unchanged lines in 1 file lost coverage.
Overall coverage decreased (-1.4%) to 53.269%

Changes Missing Coverage	Changed/Added Lines	%
cmd/mcp.go	3	0.0%
cmd/mcp_init.go	8	0.0%
internal/mcp/init/utils.go	11	0.0%
cmd/init.go	12	0.0%
internal/mcp/init/client.go	18	0.0%
internal/mcp/init/claude_code.go	28	0.0%
internal/mcp/init/init.go	59	0.0%
internal/mcp/init/cursor.go	84	0.0%
internal/mcp/init/vscode.go	86	0.0%

Files with Coverage Reduction	New Missed Lines	%
internal/gen/keys/keys.go	5	12.9%

Totals
Change from base Build 19100856468:	-1.4%
Covered Lines:	6388
Relevant Lines:	11992

💛 - Coveralls

sweatybridge · 2025-11-05T11:35:33Z

cmd/mcp.go

+var (
+	mcpCmd = &cobra.Command{
+		GroupID: groupQuickStart,
+		Use:     "mcp",


Do we plan to add other sub commands under supabase mcp? If not, I'd probably add new flags to supabase init instead.

We currently prompt users to create deno config when running supabase init which is logically similar to vscode config for mcp.

We have plans to extend the mcp command to a dev env for building mcp servers
https://www.notion.so/supabase/Supabase-CLI-Integration-635fe64201f944c1a97856cf83c565c9?source=copy_link

The Notion page is still under construction so please disregard the exact commands stated but the general idea is there.

But since these plans are for developing mcp servers using Supabase and not to configure the SUpabase MCP server using our CLI, I agree that a flag to supabase init would suit this use case better.

Something like supabase init --mcp-client=claude-code?

Rodriguespn · 2025-11-05T14:25:51Z

Addressed @sweatybridge's suggestion to move MCP configuration under supabase init:

Added a new flag: --mcp-client
Usage: supabase init --mcp-client=claude-code (also supports cursor, vscode)
This runs MCP setup after project scaffolding and configures the chosen client

Kept supabase mcp init for now to support interactive/targeted setup, but the flag should cover the review's intent. Happy to consolidate further if you'd prefer removing the mcp command entirely.

- Add main mcp command group in cmd/mcp.go - Add mcp init subcommand in cmd/mcp_init.go - Create internal/mcp/init package for implementation - Provides basic structure for interactive MCP server setup wizard This implements the foundation for AI-81: CLI init command that will: - Guide users through obtaining a Supabase PAT - Detect installed MCP clients (Cursor, VS Code, Claude Desktop) - Generate appropriate configuration files - Securely store credentials Related: https://linear.app/supabase/issue/AI-81/cli-init

Change mcpCmd.GroupID from groupManagementAPI to groupQuickStart to avoid requiring authentication before running mcp init. The init command should be accessible without prior login as it guides users through setup.

- Add --client flag to specify target MCP client - Implement client detection for Cursor, VS Code, Claude Desktop, Claude Code, Windsurf, and Cline - Generate platform-specific config templates based on official Supabase docs - Display setup instructions for each client type - Support macOS, Windows, and Linux config paths

…ude Code - Add configureJSONClient() to automatically create/update mcp.json files - Support project-local and global configuration options - Prompt for project reference interactively - Handle existing configs by merging (not overwriting) - Add configureClaudeCode() to use Claude CLI for configuration - Detect if Claude CLI is available and run 'claude mcp add' command - Display step-by-step next actions after configuration - Mark clients as CanAutomate: cursor, vscode, claude-code

- Add actual client binary/app detection instead of just checking config directories - Add isClientInstalled() that checks for: * Cursor: cursor binary or Cursor.app * VS Code: code binary * Claude Desktop: Claude.app * Claude Code: claude CLI * Windsurf: windsurf binary or Windsurf.app * Cline: VS Code (as it's an extension) - Switch from local NPX server to remote OAuth server at https://mcp.supabase.com/mcp - Update config templates to use remote server format with: * type: 'remote' * url: https://mcp.supabase.com/mcp * OAuth configuration with api.supabase.com * SUPABASE_MCP_SERVER_PERSONAL_ACCESS_TOKEN env var - Show manual config instructions when client not installed - Separate installed vs. available clients in interactive mode - Update Claude Code auto-config to use 'remote' command instead of npx - Update all manual instruction templates to use remote server format

- Add Codex to the list of supported MCP clients - Add getCodexConfigPath() for platform-specific config paths: * macOS: ~/Library/Application Support/Codex/mcp.json * Windows: ~/AppData/Roaming/Codex/mcp.json * Linux: ~/.config/Codex/mcp.json - Add Codex detection via 'codex' binary or Codex.app - Add Codex-specific manual configuration instructions - Update supported clients list to include Codex with URL: https://codex.so - Set CanAutomate to false (manual configuration only)

- Fix import formatting with goimports - Add error checking for fmt.Scanln calls - Lowercase error messages (ST1005) - Remove redundant newlines in fmt.Println - Remove unused ctx parameter from configureJSONClient - Add #nosec G204 comment for validated command execution - Apply gofmt formatting to all files

- Introduced Client interface for extensible MCP client support - Implemented client registry pattern for easy addition of new clients - Refactored Claude Code implementation to use new interface - Added documentation for adding new clients - Supports auto-detection of installed clients - Currently supports Claude Code with foundation for more clients

- Implemented cursorClient with JSON config file approach - Supports both project-local (.cursor/mcp.json) and global configs - Adds Supabase MCP server URL to mcpServers configuration - Merges with existing config if present - Added appExists helper for macOS app detection - Updated help text to mention Cursor support

- Created baseClient struct with common Client interface methods - Refactored claudeCodeClient and cursorClient to embed baseClient - Added constructor functions (newClaudeCodeClient, newCursorClient) - Reduced code duplication by using composition pattern - Updated example template to show new pattern - Each client now only implements Configure() method

- Implemented vscodeClient with JSON config file approach - Supports both project-local (.vscode/mcp.json) and global configs - Adds Supabase MCP server with type: http and URL - Merges with existing config if present - Updated help text to mention VS Code support - Checks for 'code' command availability

Reorganized MCP init package for better scalability and maintainability: - client.go: Base Client interface and baseClient implementation - claude_code.go: Claude Code client implementation - cursor.go: Cursor client implementation - vscode.go: VS Code client implementation - utils.go: Helper functions (appExists) - init.go: Core logic, client registry, and orchestration Benefits: - Each client is now in its own file for easy maintenance - Adding new clients is simpler - just create a new file - Reduced init.go from 425 to ~100 lines - Better separation of concerns - Easier to navigate and understand

- Adds --mcp-client flag to supabase init (e.g., --mcp-client=claude-code) - Wires to internal MCP setup after project scaffolding - Addresses review feedback to avoid a top-level mcp command for config

Rodriguespn · 2025-11-05T16:44:07Z

Hey @sweatybridge, brainstormed about this with @gregnr and we've decided to go on a different direction. It's still under development but I'll change the Linear issue with the new approach to this once we have it.
Converting this PR into a draft one

Rodriguespn requested review from gregnr and mattrossman October 29, 2025 15:31

Rodriguespn self-assigned this Oct 29, 2025

Rodriguespn marked this pull request as ready for review November 4, 2025 17:01

Rodriguespn requested a review from a team as a code owner November 4, 2025 17:01

sweatybridge reviewed Nov 5, 2025

View reviewed changes

Rodriguespn added 14 commits November 5, 2025 14:34

fix: move mcp command to Quick Start group

24c0120

Change mcpCmd.GroupID from groupManagementAPI to groupQuickStart to avoid requiring authentication before running mcp init. The init command should be accessible without prior login as it guides users through setup.

feat(init): add --mcp-client flag to configure MCP during project init

cc31267

- Adds --mcp-client flag to supabase init (e.g., --mcp-client=claude-code) - Wires to internal MCP setup after project scaffolding - Addresses review feedback to avoid a top-level mcp command for config

fix: apply gofmt formatting to cmd/init.go and internal/mcp/init/init.go

79948e4

Rodriguespn force-pushed the feat/mcp-init-command branch from 997f4ca to 79948e4 Compare November 5, 2025 14:34

Rodriguespn marked this pull request as draft November 5, 2025 16:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(mcp): add `supabase mcp init` command to configure MCP clients #4383

feat(mcp): add `supabase mcp init` command to configure MCP clients #4383

Uh oh!

Rodriguespn commented Oct 29, 2025 •

edited

Loading

Uh oh!

coveralls commented Oct 29, 2025 •

edited

Loading

Uh oh!

sweatybridge Nov 5, 2025

Uh oh!

Rodriguespn Nov 5, 2025

Uh oh!

Rodriguespn commented Nov 5, 2025

Uh oh!

Rodriguespn commented Nov 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

feat(mcp): add supabase mcp init command to configure MCP clients #4383

Are you sure you want to change the base?

feat(mcp): add supabase mcp init command to configure MCP clients #4383

Uh oh!

Conversation

Rodriguespn commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

How

Features

Architecture

Client-Specific Configurations

Usage Examples

Related

Uh oh!

coveralls commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 19105505226

Details

💛 - Coveralls

Uh oh!

sweatybridge Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

Rodriguespn Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

Rodriguespn commented Nov 5, 2025

Uh oh!

Rodriguespn commented Nov 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

feat(mcp): add `supabase mcp init` command to configure MCP clients #4383

feat(mcp): add `supabase mcp init` command to configure MCP clients #4383

Rodriguespn commented Oct 29, 2025 •

edited

Loading

coveralls commented Oct 29, 2025 •

edited

Loading