Cursor MCP setup: mcp.json, one-click install links and OAuth

In short: Cursor reads MCP servers from mcp.json, either globally at ~/.cursor/mcp.json or per project at .cursor/mcp.json. A remote server is a url entry; a local one is a command with args. Save the file, open Cursor Settings → Tools & MCP, sign in when the server shows Needs login, and the tools are available to the Agent. Servers can also be shared as a one-click install link; the UnifAPI one is below.

Cursor's MCP support is file-based, which is good news: there is nothing to click through except the OAuth sign-in, the configuration is committable, and the same JSON shape works for every server. This guide uses the UnifAPI MCP server (https://mcp.unifapi.com, live public data from X, Instagram, TikTok, YouTube, Reddit, LinkedIn, Threads and the SEO stack) as the worked example.

Where mcp.json lives

Both files share the same shape, and Cursor merges them. If a name appears in both, the project entry wins.

A remote server: the url shape

Create or edit the file and add the server under mcpServers:

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

Save. Open Cursor Settings → Tools & MCP (older builds: MCP & Integrations). The server appears with a status dot. For an OAuth-protected server such as UnifAPI it reads Needs login: click it, sign in or create a UnifAPI account in the browser window, and approve the read-only scope. The dot turns green and the tool list expands under the server: list_operations, get_operation and call_api.

Cursor supports OAuth 2.0 dynamic client registration, which is what UnifAPI uses, so no client ID is needed. For providers that hand out a fixed client ID or require a whitelisted redirect URL, Cursor accepts an auth block next to url with CLIENT_ID, an optional CLIENT_SECRET and scopes. UnifAPI does not need it.

A remote server that uses a static token instead of OAuth takes headers, and the value can come from your environment:

{
  "mcpServers": {
    "example": {
      "url": "https://mcp.example.com",
      "headers": {
        "Authorization": "Bearer ${env:EXAMPLE_TOKEN}"
      }
    }
  }
}

UnifAPI accepts a workspace API key this way, but OAuth is the recommended path: nothing secret in a file, and the token is read-only.

A local server: the command shape

A server that runs on your machine is a command Cursor starts:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"],
      "env": {
        "NODE_OPTIONS": "--max-old-space-size=512"
      }
    }
  }
}

${workspaceFolder}, ${userHome} and ${env:NAME} are interpolated, so a committed .cursor/mcp.json can stay machine-independent. command and url are exclusive; an entry with both is ignored.

One-click install links

Cursor can install a server from a deeplink, which is how vendors put an "Add to Cursor" button on their docs. The link carries the server name and the same JSON you would write by hand, base64-encoded:

cursor://anysphere.cursor-deeplink/mcp/install?name=$NAME&config=$BASE64_CONFIG

For UnifAPI, config is the base64 of {"url":"https://mcp.unifapi.com"}:

cursor://anysphere.cursor-deeplink/mcp/install?name=unifapi&config=eyJ1cmwiOiJodHRwczovL21jcC51bmlmYXBpLmNvbSJ9

Opening it in a browser hands the server to Cursor, which asks you to confirm before writing it to your global mcp.json. Generate your own with echo -n '{"url":"https://…"}' | base64 and swap the two parameters. Links are convenient for onboarding; a committed .cursor/mcp.json is still the right choice for a team.

Using the tools

MCP tools are used by the Agent (the default chat mode), not by inline edits or Tab. Ask for something the server can answer and watch for the tool call:

Using the unifapi MCP server, list the operations available for TikTok and tell me which one returns a creator's recent videos.

Cursor asks before running a tool unless you enable auto-run for that server in the MCP settings. For a read-only server like UnifAPI, auto-run is reasonable: the only thing a call can spend is workspace credits, and get_operation shows the per-record price before call_api runs.

Cursor sends the model a limited number of tools at once (around forty across all enabled servers) and disables the rest, so prefer servers with a small tool surface. UnifAPI's catalog is behind three tools on purpose; a large catalog exposed as one tool per endpoint would be mostly disabled.

A first task on UnifAPI

A bounded prompt that exercises the whole loop:

With the unifapi MCP tools: find the Reddit threads from the last 7 days that mention "Cursor MCP", pull the top 20 by score, and summarise the recurring setup problems with one example thread each. Call list_operations and get_operation before call_api.

Billing is per public-data record in workspace credits ($0.001 each; one credit for most records, higher floors published in the catalog). Model tokens stay on your Cursor plan. A new UnifAPI workspace has no credits until its first top-up, which carries a one-time bonus, so top up once before the first call_api.

If you want to start from a job rather than an endpoint, the platform agents (Reddit, X, LinkedIn, TikTok, YouTube, Instagram, Threads) and the SEO agent each carry a ready prompt and the operations it needs.

Troubleshooting

Sources checked

Written on October 14, 2026 against Cursor's MCP documentation (configuration shapes, OAuth, interpolation) and the install links reference. Settings labels change between Cursor releases; the file format has been stable.

What to read next

MCP setup - the hosted connector instructions for every client.

How to add an MCP server to Claude - connectors, claude_desktop_config.json and claude mcp add.

Codex MCP setup - codex mcp add and config.toml.

Agent context: rules, Skills and MCP - where MCP fits next to rules files and Skills.