By default, Cursor AI can read the files inside your local repository, but it is completely blind to your live production database schema, GitHub pull requests, and external documentation. That is why thousands of full-stack developers are configuring Model Context Protocol (MCP) servers inside Cursor to turn their code editor into a true autonomous agent.
However, setting up MCP servers in Cursor AI for the first time rarely goes smoothly. Developers routinely hit three frustrating walls: the dreaded red status light showing Client closed, Windows path failures where Cursor cannot locate npx, and confusing global versus project-level mcp.json configurations.
In this step-by-step engineering guide, you will get copy-paste .cursor/mcp.json configuration blueprints for Supabase (PostgreSQL) and GitHub, along with the exact cross-platform command fix that turns every MCP status indicator green in under two minutes.
.cursorrules file from How to Open & Migrate a Bolt.new Project in Cursor AI (Fix Token Limits & Context Loss).
Architecture Overview: How Cursor Composer Talks to MCP Servers
Originally introduced as an open standard by Anthropic, the Model Context Protocol (MCP) acts as a universal USB-C port for AI IDEs. Instead of manually copying and pasting SQL table schemas or GitHub issue descriptions into Cursor's chat sidebar, Cursor Composer (in Agent Mode) spawns a lightweight local Node.js or Python subprocess via stdio (Standard Input/Output) and queries your live tools directly.
+-------------------------------------------------------------------------+
| CURSOR AI (COMPOSER AGENT MODE) |
| |
| Prompt: "Check my live Supabase tables and create a migration script" |
+------------------------------------+------------------------------------+
|
Reads .cursor/mcp.json Config
|
+-----------------------------+-----------------------------+
| (Spawns Local stdio Node) | (Spawns Local stdio Node)
v v
+------+--------------------------+ +------------------+--------------+
| SUPABASE / POSTGRES MCP SERVER | | GITHUB MCP SERVER |
| @supabase/mcp-server-supabase | | @modelcontextprotocol/github |
| * Inspects live tables & RLS | | * Reads PRs, Issues & Commits |
| * Executes read/write SQL | | * Creates branches via API |
+---------------------------------+ +---------------------------------+
Step 1: Create Your Project-Scoped .cursor/mcp.json File
While you can add MCP servers globally inside Cursor's UI settings, storing your configuration inside a project-scoped .cursor/mcp.json file is far cleaner—especially when different projects connect to different Supabase databases.
- Open your project folder in Cursor AI.
- In the left file explorer, create a folder named
.cursorin your project root (if it doesn't already exist). - Inside
.cursor/, create a new file namedmcp.json. - Immediately add
.cursor/mcp.jsonto your.gitignorefile so you never commit personal access tokens to GitHub!
Step 2: Copy-Paste mcp.json Blueprint (Supabase + GitHub)
Depending on your operating system, copy either the macOS / Linux configuration or the Windows configuration below and paste it into .cursor/mcp.json.
Option A: For macOS & Linux Developers
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": [
"-y",
"@supabase/mcp-server-supabase@latest",
"--access-token",
"sbp_your_supabase_personal_access_token_here"
]
},
"github": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_github_token_here"
}
}
}
}
Option B: For Windows 10/11 Developers (Fixes the "Client Closed" Bug!)
On Windows, Cursor's background process spawner cannot execute npx directly because npx is actually a npx.cmd batch wrapper. If you use "command": "npx" on Windows, Cursor immediately throws Client closed or spawn npx ENOENT. Wrapping the command with cmd /c fixes it permanently:
{
"mcpServers": {
"supabase": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"@supabase/mcp-server-supabase@latest",
"--access-token",
"sbp_your_supabase_personal_access_token_here"
]
},
"github": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_github_token_here"
}
}
}
}
Step 3: Where to Grab Your Supabase & GitHub Personal Access Tokens
Note that the Supabase MCP server requires a Personal Access Token (sbp_...) from your account dashboard—not your project's public `anon` key.
- To get your Supabase Token: Visit
supabase.com/dashboard/account/tokens, click Generate new token, copy the string starting withsbp_, and paste it into yourmcp.jsonfile. - To get your GitHub Token: Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic), generate a token with the
reposcope checked, and paste theghp_string intoGITHUB_PERSONAL_ACCESS_TOKEN.
Step 4: Activate & Test Your MCP Tools in Cursor Composer (Ctrl + I)
- Save
.cursor/mcp.jsonand open Cursor Settings (Ctrl + Shift + J) → MCP. - Click the Refresh icon next to your listed servers. Within 3–5 seconds, the status indicator dot next to
supabaseandgithubwill turn solid green and display the discovered tools (`execute_sql`, `list_tables`, `create_pull_request`, etc.). - Open Cursor Composer (
Ctrl + I) and make sure the mode dropdown is set to Agent (MCP tools only run in Agent mode, not normal Ask/Chat mode). - Test your connection with this exact prompt:
Use the Supabase MCP server to inspect all tables and Row Level Security (RLS) policies in my public schema. Then check if my local TypeScript interfaces in `src/types/` match the live database columns.
Troubleshooting Matrix: Fixing Cursor MCP Server Errors
If your MCP status light stays red or Yellow inside Cursor Settings, match your error message below for the immediate fix:
| Cursor MCP Error / Symptom | Root Cause | Exact Engineering Fix |
|---|---|---|
Client closed (Red Dot on Windows) |
Windows cannot spawn npx directly without invoking the command shell wrapper. |
Change "command": "npx" to "command": "cmd" and prepend "/c", "npx" to your args array (see Option B above). |
spawn npx ENOENT (macOS / Linux with NVM) |
Cursor's GUI app doesn't inherit your NVM or Homebrew `$PATH` from `.zshrc`. | Run which npx in your terminal and paste the full absolute path (e.g., /Users/you/.nvm/versions/node/v20.18.0/bin/npx) into "command". |
| Green Dot, But Composer Ignores MCP Tools | Composer is set to Normal / Ask mode instead of Agent mode, or you are using a custom model that doesn't support tool calling. | Switch Composer dropdown to Agent and select Claude 3.5/3.7 Sonnet, Opus 5.5, or Gemini 4 Argon. |
401 Unauthorized on Supabase MCP queries |
Pasted the project `anon` JWT key (`eyJ...`) instead of a Personal Access Token (`sbp_...`). | Generate a Personal Access Token at supabase.com/dashboard/account/tokens and restart the MCP server. |
Frequently Asked Questions (FAQ)
Is it safe to give Cursor MCP write access to my production Supabase database?
By default, Cursor asks for explicit human confirmation before executing any destructive MCP tool call, or you can pass the --read-only flag inside your mcp.json args array (right after @supabase/mcp-server-supabase@latest) so Cursor can inspect schemas and run `SELECT` queries without ever modifying live rows.
Why shouldn't I commit .cursor/mcp.json to GitHub?
Because .cursor/mcp.json stores raw API credentials like your Supabase sbp_ token and GitHub ghp_ token, committing it to a repository will expose your infrastructure keys and trigger GitHub secret-scanning alerts. Always add .cursor/mcp.json to your .gitignore file before following our GitHub and Vercel deployment guide.
Can I use these exact MCP configurations in VS Code or Claude Desktop?
Yes! Because Model Context Protocol is an open standard, the exact same mcpServers JSON block works inside Claude Desktop (`claude_desktop_config.json`), Cline in VS Code, and Windsurf.
Comments (0)