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

Add an MCP server to Cursor: where mcp.json lives, remote url vs local command shapes, OAuth sign-in, and the one-click install link you can share.

- URL: https://unifapi.com/blog/cursor-mcp-setup
- Published: 2026-10-14
- Category: Agents
- Keywords: cursor mcp, cursor mcp setup, cursor mcp.json, add mcp server to cursor, cursor mcp install link, cursor remote mcp server, cursor mcp oauth
- Author: Unif Agents team

> 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

| File                 | Scope                                      | Use it for                                                            |
| -------------------- | ------------------------------------------ | --------------------------------------------------------------------- |
| `~/.cursor/mcp.json` | Every project on this machine, this user   | Servers you want everywhere (a data server, a browser, a docs server) |
| `.cursor/mcp.json`   | One project, committed with the repository | Servers that belong to the codebase; teammates get them on clone      |

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`:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

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

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

```text
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](/agents/reddit) (Reddit, [X](/agents/x-twitter), [LinkedIn](/agents/linkedin), [TikTok](/agents/tiktok), [YouTube](/agents/youtube), [Instagram](/agents/instagram), [Threads](/agents/threads)) and the [SEO agent](/agents/seo) each carry a ready prompt and the operations it needs.

## Troubleshooting

| Symptom                                    | What to do                                                                                                                     |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| Server not listed after saving `mcp.json`  | Validate the JSON (no trailing commas); toggle the server off and on in Tools & MCP, or reload the window                      |
| **Needs login** never clears               | Pop-ups blocked, or the OAuth window signed in to a different account; click the status again, or remove and re-add the server |
| Tools listed but greyed out                | You are over Cursor's active-tool limit; disable a server you are not using                                                    |
| Agent answers without calling the tool     | Name the server in the prompt once ("using the unifapi MCP server"); after one successful call it reaches for it on its own    |
| `call_api` returns `insufficient_credits`  | The workspace has no credits yet; top up once in the UnifAPI console and rerun                                                 |
| A teammate does not see the project server | `.cursor/mcp.json` is not committed, or their Cursor has not trusted the workspace yet                                         |

## Sources checked

Written on October 14, 2026 against Cursor's [MCP documentation](https://cursor.com/docs/mcp) (configuration shapes, OAuth, interpolation) and the [install links reference](https://cursor.com/docs/mcp/install-links). Settings labels change between Cursor releases; the file format has been stable.

## What to read next

[MCP setup](/mcp) - the hosted connector instructions for every client.

[How to add an MCP server to Claude](/blog/how-to-add-an-mcp-server-to-claude) - connectors, `claude_desktop_config.json` and `claude mcp add`.

[Codex MCP setup](/blog/codex-mcp-setup) - `codex mcp add` and `config.toml`.

[Agent context: rules, Skills and MCP](/blog/ai-agent-context-rules-skills-mcp) - where MCP fits next to rules files and Skills.