datatomcp
Sign inStart free

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

By Killian, founder · Updated 27 October 2026 · Markdown

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:

{
  "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, 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:

{
  "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, add a CSV or Google Sheet under Add data, and paste the JSON above. The CSV MCP server guide 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 · Claude Code · VS Code