Add a remote MCP server to Cursor
Cursor reads MCP servers from an mcp.json file with an mcpServers object. A remote server needs a url, and a headers object if it takes a key.
By Jake Marsh. Checked against Cursor's own docs on 2026-10-31; each section links its source.
The Cursor config
For a server named my-server at https://example.com/mcp that takes an Authorization header. Where it goes: ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).
{
"mcpServers": {
"my-server": {
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Swap in your own server below and the Cursor version updates first, with every other client after it.
Where Cursor reads it
~/.cursor/mcp.jsonglobal: tools available in every project.cursor/mcp.json in the projectproject: tools for that project only
Source: cursor.com/docs/context/mcp
Keys, headers and sign-in
Put a static key in headers. Cursor resolves variables in command, args, env, url and headers: ${env:NAME} reads an environment variable, and ${userHome} and ${workspaceFolder} (the folder that contains .cursor/mcp.json) are also available. That keeps the key itself out of a file you might commit.
For OAuth servers, Cursor signs in as a public client through dynamic client registration. A provider that needs a pre-registered app gets an auth object on the entry with CLIENT_ID, an optional CLIENT_SECRET and optional scopes.
{
"mcpServers": {
"my-server": {
"url": "https://example.com/mcp",
"headers": { "Authorization": "Bearer ${env:MY_SERVER_KEY}" }
}
}
}Source: cursor.com/docs/context/mcp
Check that it connected
Turn servers on or off from Customize in the sidebar. A disabled server doesn't load or appear in chat. The tools Cursor can use from a server are listed under Available Tools.
When a server doesn't load, open the Output panel (Cmd+Shift+U) and choose MCP Logs. It shows initialization, tool calls and errors.
Source: cursor.com/docs/context/mcp
Cursor gotchas
envFile works for stdio servers only. For a remote server, set the variable in your shell profile or system environment and reference it with ${env:NAME} in url or headers.
Source: cursor.com/docs/context/mcp
Cursor asks for approval before it uses MCP tools, by default, so the first call to a new server waits for you.
Source: cursor.com/docs/context/mcp
For a provider with a pre-registered OAuth app, register both redirect URLs: https://www.cursor.com/agents/mcp/oauth/callback (web and Cursor Agents) and http://localhost:8787/callback (desktop app). Cloud Agents keep their own sign-ins, separate from the desktop app.
Source: cursor.com/docs/context/mcp
On enterprise setups a remote URL must match an admin-approved URL pattern, or the server won't connect.
Source: cursor.com/docs/context/mcp
Still not connecting? Cursor MCP server not showing tools walks through the fixes in order.
Generate the config for your server
Runs in your browser. Nothing you type is sent anywhere. Still, don't paste real keys on shared screens.
Cursor
~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project)
{
"mcpServers": {
"my-server": {
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: cursor.com/docs/context/mcp
Claude Code
Run in a terminal (--scope user makes it available in every project)
claude mcp add --transport http --scope user my-server "https://example.com/mcp" --header "Authorization: Bearer YOUR_KEY"Source: code.claude.com/docs/en/mcp
Codex CLI
~/.codex/config.toml
[mcp_servers.my_server]
url = "https://example.com/mcp"
http_headers = { "Authorization" = "Bearer YOUR_KEY" }Source: developers.openai.com/codex/mcp
Windsurf / Devin Desktop
~/.config/devin/mcp_config.json (older Windsurf: ~/.codeium/windsurf/mcp_config.json)
{
"mcpServers": {
"my-server": {
"serverUrl": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Devin CLI / Devin Local
Run in a terminal (-s user saves it to ~/.config/devin/mcp_config.json for every project)
devin mcp add -s user -H "Authorization: Bearer YOUR_KEY" my-server "https://example.com/mcp"VS Code (Copilot agent mode)
.vscode/mcp.json in the workspace, or your user mcp.json (MCP: Open User Configuration)
{
"servers": {
"my-server": {
"type": "http",
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: code.visualstudio.com/docs/agents/reference/mcp-configuration
Gemini CLI
~/.gemini/settings.json (or .gemini/settings.json in the project)
{
"mcpServers": {
"my-server": {
"httpUrl": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Antigravity CLI (agy)
~/.gemini/config/mcp_config.json (or .agents/mcp_config.json in the workspace)
{
"mcpServers": {
"my-server": {
"serverUrl": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: antigravity.google/docs/mcp
Cline
cline_mcp_settings.json (in the Cline panel, MCP Servers > Configure > Configure MCP Servers; Cline CLI: ~/.cline/data/settings/cline_mcp_settings.json)
{
"mcpServers": {
"my-server": {
"type": "streamableHttp",
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: docs.cline.bot/mcp/mcp-overview
OpenCode
opencode.json in the project root, or ~/.config/opencode/opencode.json for every project
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"my-server": {
"type": "remote",
"url": "https://example.com/mcp",
"oauth": false,
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Source: opencode.ai/docs/mcp-servers/
Need a task list for those agents?
Taskhold is a remote MCP server that gives Cursor and your other agents a task list you share, with their progress on a live board. Its setup link writes this config for the agent, so you don't have to. $12 a month or $120 a year, 7-day trial.
Add Taskhold to Cursor in one click
- Add to CursorOpens Cursor on this computer, then asks you to sign in to Taskhold. No key to copy. Needs a Taskhold subscription or trial.