Where Cursor’s MCP config lives, what goes in it, which transports it supports, and how to fix the common failures — plus how to put a policy gate in front of every tool call.
QUICK ANSWERQuick answer: project-level config in .cursor/mcp.json, global config in ~/.cursor/mcp.json. Top-level key is mcpServers.
| Scope | Path | Notes |
|---|---|---|
| Project | .cursor/mcp.json | In the project root. Servers defined here load only in that project. |
| Global | ~/.cursor/mcp.json | In your home directory. Servers available in every project. |
The Cursor CLI shares the same mcp.json files as the editor — one config covers both.
Both files use the same shape: a top-level mcpServers object, one entry per server. Local servers declare a command; remote servers declare a url.
| Key | What it does |
|---|---|
command | Executable to launch a local (stdio) server. Must be on PATH or a full path. |
args | Array of arguments passed to the command. |
env | Environment variables for the server process. |
envFile | Path to an env file — stdio servers only. |
url | Endpoint for a remote server. Cursor auto-detects streamable HTTP vs SSE from the endpoint. |
headers | HTTP headers sent with every request to a remote server — where auth tokens go. |
auth | Static OAuth client credentials (CLIENT_ID, optional CLIENT_SECRET and scopes) for providers without dynamic client registration. |
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
}
}
}
} REMOTE SERVER (HTTP):
{
"mcpServers": {
"my-remote": {
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
} Cursor interpolates ${env:NAME}, ${userHome}, ${workspaceFolder} and ${pathSeparator} inside command, args, env, url and headers — useful for keeping tokens out of committed config.
| Transport | Status | How to declare it |
|---|---|---|
| stdio | Supported | Declare command + args. Runs as a local child process. |
| Streamable HTTP | Supported | Declare url. Auto-detected. Supports OAuth. |
| SSE | Supported | Declare url pointing at an SSE endpoint. Auto-detected. Supports OAuth. |
Create .cursor/mcp.json (project) or ~/.cursor/mcp.json (global) and add an entry under mcpServers. Cursor picks it up without a restart in most cases; toggle the server in settings if it doesn’t appear.
Open Cursor Settings (Cmd/Ctrl+Shift+J) → Tools & MCP. Add, enable, disable or toggle servers, and see each server’s tool count.
The Cursor marketplace and “Add to Cursor” deeplink buttons install a server and run its OAuth flow in one step. Server authors generate the buttons from Cursor’s deeplink docs.
Cmd+Shift+U) and select MCP Logs — it shows initialisation, tool calls and errors.The command must be on PATH or given as a full path. GUI-launched apps don’t always inherit your shell PATH; which npx in a terminal gives you the absolute path to use.
Toggle the server off and on in Settings → Tools & MCP to reload it. For changes to a custom local server’s code, restart Cursor.
Remove the server from settings, run npm cache clean --force, then re-add it — npx caches aggressively.
The error surfaces in chat and the tool is marked failed; other servers are isolated and keep working. Retry the call, then check MCP Logs for the underlying error.
For providers without dynamic client registration, set static credentials in the auth block and whitelist Cursor’s fixed redirect URI: cursor://anysphere.cursor-mcp/oauth/callback.
A standard MCP server in your Cursor config. Tool calls hit GitHub directly with no policy gate.
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
}
}
}
} Register the GitHub MCP in PolicyLayer, mint a grant, point Cursor at the proxy URL. PolicyLayer evaluates every call against the grant’s policy before it reaches GitHub — and the token leaves your config.
{
"mcpServers": {
"github": {
"url": "https://proxy.policylayer.com/mcp/<server-uuid>/",
"headers": {
"Authorization": "Bearer <grant-token>"
}
}
}
} The <server-uuid> appears on each server's detail page. The <grant-token> shows once at mint time. See the Quick start for the full setup walk-through — and if you operate under SOC 2, HIPAA, GDPR or similar, the compliance hub maps how gateway-mediated MCP traffic evidences each framework.
Allow listing and issue creation. Deny merges into main. Deny everything else by default.
{
"version": "1",
"default": "deny",
"tools": {
"list_repositories": {},
"create_issue": {},
"merge_pull_request": {
"deny_if": [
{
"conditions": [
{ "path": "args.base", "op": "eq", "value": "main" }
]
}
]
}
}
} See Writing policies for the policy format, operators, and quota shapes.
Project-level servers go in .cursor/mcp.json at the project root. Global servers go in ~/.cursor/mcp.json in your home directory. Both use the same mcpServers format, and the Cursor CLI reads the same files.
Yes. Declare a url instead of a command and Cursor auto-detects streamable HTTP or SSE. Auth goes in the headers block, or in the auth block for OAuth providers with static client credentials.
Usually not — Cursor picks up config changes, and toggling the server off and on in Settings → Tools & MCP forces a reload. A full restart is only needed when the code of a custom local server changes.
Open the Output panel (Cmd+Shift+U) and select MCP Logs. It shows server initialisation, every tool call, and errors. The settings page also shows whether the server loaded and how many tools it exposes.
Cursor prompts for approval per tool by default, and Run Mode allowlists can auto-approve specific tools. For deterministic enforcement with audit logs — rules on tool arguments, rate limits, spend caps — route the server through a policy gateway like PolicyLayer.
Route your MCP traffic through PolicyLayer. Every tool call is checked against your policy before it runs: allow, deny, or require approval. Per-identity grants. Full audit log. Live in minutes.
Instant setup, no code required.
46,500+ MCP servers and 515,000+ tools scanned and risk-classified.