# Cursor MCP: add a remote MCP server to mcp.json

> Add a remote MCP server to Cursor: mcp.json locations, OAuth and header sign-in, how to check the tools loaded and read MCP Logs.

Source: https://datatomcp.com/guides/cursor-mcp · By Killian · Updated 2026-10-27

To add a remote MCP server to Cursor, put its URL in `mcp.json` under `mcpServers` (`~/.cursor/mcp.json` for every project, `.cursor/mcp.json` for one project), then turn the server on in **Customize** in the sidebar and sign in when Cursor asks. Servers listed in Cursor's marketplace install with **Add to Cursor** instead. Cursor's menus have been renamed several times, but the file has stayed the same, so this guide works from the file.

The example server is datatomcp, which lets Cursor's agent query your CSVs and Google Sheets.

## 1. Add the server to mcp.json

Open (or create) `~/.cursor/mcp.json` and add:

```json
{
  "mcpServers": {
    "datatomcp": {
      "url": "https://app.datatomcp.com/mcp"
    }
  }
}
```

That's all an OAuth server needs. Cursor supports Streamable HTTP and SSE for remote servers.

**Global or project?** `~/.cursor/mcp.json` applies to every project. `.cursor/mcp.json` in a repo applies to that project and can be committed so your team gets the server too. If both define the same name, the project entry wins.

**From the UI.** Recent builds open the same file from **Customize** in the sidebar; some 2026 builds have **Cursor Settings → Tools & MCP → New MCP Server** instead. Either way you end up editing `mcp.json`.

**One-click.** datatomcp is listed at [cursor.directory/plugins/datatomcp](https://cursor.directory/plugins/datatomcp), with the MCP server and a get-started skill. Installing from there writes the same entry.

## 2. Sign in

Open **Customize**, find the server and switch it on. Cursor detects that the server needs OAuth and opens your browser. For datatomcp you sign in with your datatomcp account and approve read access to your datasets. When you return, the server shows its tools.

### Servers that use an API key

Use `headers`, with an environment variable rather than the literal secret:

```json
{
  "mcpServers": {
    "my-api": {
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer ${env:MY_API_TOKEN}" }
    }
  }
}
```

Some servers require a pre-registered OAuth app. Cursor accepts an `auth` object with `CLIENT_ID`, an optional `CLIENT_SECRET` and `scopes`. Servers like datatomcp that support dynamic registration don't need it.

## 3. Check it worked

- In **Customize**, the server's toggle is on and its tools are listed. A server with no tools listed usually hasn't finished sign-in.
- Open the agent chat and ask: "Use datatomcp to list my datasets." Cursor shows the tool call and asks to run it (unless you've allowed it to run tools automatically).
- If nothing happens, open the Output panel (**Cmd+Shift+U** on macOS, **Ctrl+Shift+U** on Windows and Linux) and choose **MCP Logs** from the dropdown.

## Troubleshooting

- **Server shows red or "error" in Customize.** Check **MCP Logs**. A 401 means sign-in is missing or expired; sign in again from the server entry in **Customize**.
- **JSON parse error.** A trailing comma or a missing brace in `mcp.json` stops every server in that file from loading.
- **The agent doesn't use the tools.** Name the server in your prompt, and make sure you're in Agent mode, which is the mode that calls tools.
- **Too many tools.** Each enabled server adds tool descriptions to every request. Switch off servers you aren't using in **Customize**.
- **Team member can't connect to a committed server.** Each person signs in with their own account the first time; tokens aren't shared through `.cursor/mcp.json`.

## A data server for Cursor

Coding agents often need data that isn't in the repo: a pricing sheet, a list of customers to seed a test, an export to check a migration against. Pasting that into the chat is slow and the model reads it as text. With datatomcp connected, the agent asks questions instead:

> Use datatomcp: which plan has the most active customers in the customers sheet, and how many are on each plan?

It calls `distinct_values` to read the real plan names, then `aggregate` grouped by plan. The counts are computed by a database over every row. The five tools are read-only, so the agent can't change your data.

[Create a free account](https://app.datatomcp.com/login), add a CSV or Google Sheet under **Add data**, and paste the JSON above. The [CSV MCP server guide](/guides/csv-mcp-server) explains the CSV side.

## FAQ

**Where is Cursor's MCP config file?** `~/.cursor/mcp.json` (global) and `.cursor/mcp.json` in a project.

**Does Cursor support remote MCP servers with OAuth?** Yes, over Streamable HTTP and SSE. It discovers the sign-in from the server URL.

**Can I use variables in mcp.json?** Yes: `${env:NAME}` for environment variables, plus `${userHome}` and `${workspaceFolder}`.

**Do MCP servers work in Cursor's web and background agents?** Cursor's docs list a separate OAuth callback for web agents, and not every server accepts it. Test in the desktop app first.

More clients: [Add a remote MCP server to any AI client](/guides/add-remote-mcp-server) · [Claude Code](/guides/claude-code-mcp) · [VS Code](/guides/vscode-mcp)