Cursor MCP Setup: mcp.json, Settings and Marketplace

You paste a snippet into a config file, restart the editor, and the new server sits there with a red dot next to its name. That moment is why a clean Cursor MCP setup matters. The Model Context Protocol lets Cursor's Agent call outside tools, from a browser to a database to an image generator, but only when the connection is wired correctly. This article follows the path in order. You will see where mcp.json lives, how to write local and remote entries, which switches sit in Settings, how the Marketplace installs servers in one click, and what to check when something fails. Every config below uses field names from Cursor's own documentation, and every secret stays out of the file.

What MCP Does Inside Cursor

MCP is an open protocol that gives an AI client a standard way to talk to outside programs. Cursor is the client. Each program you connect is a server, and each server exposes tools the Agent can call during a chat: read a file, query a database, open a web page, file a ticket, generate an image.

Servers, Tools and the Agent

Think of three layers. The Agent decides what you asked for. The server advertises what it can do. A tool is one action with a name, a description and a set of inputs. When you ask Cursor to find out why an endpoint returns a 500, the Agent reads the tool list, picks the ones that fit, and asks permission before it runs them.

Two practical consequences follow:

• More servers is not better. Every enabled tool adds its description to the context the Agent reads, so a dozen unused servers make answers slower and choices worse.
• Names matter. Clear labels such as github or project-files make approval prompts easy to read later.

💡 Start with one or two servers you will use every day. Add the rest when a real task asks for them.

Here is what that looks like in daily work. A browser server lets the Agent open your staging site, click through a checkout and report what broke. A GitHub server lets it read an issue, find the matching code and draft the pull request text. A database server lets it check a row before it suggests a migration. In each case the Agent stops guessing and starts reading real data, which is the whole reason to spend ten minutes on configuration.

Local or Remote Server

Cursor supports three transports, and the choice decides how you write the entry in mcp.json.

A stdio server is the simplest: Cursor launches a command such as npx and talks to it through standard input and output. A remote server is just a URL. You trust the provider to run it, and you often sign in through the browser with OAuth instead of pasting a token.

Where mcp.json Lives

Cursor reads MCP definitions from a JSON file named mcp.json. There are two places for it, and you can use both at once.

Global File or Project File

On Windows the home folder is your user profile, so the global file sits at C:\Users\YourName\.cursor\mcp.json.

Cursor merges the two files. Give servers different names in each so you never wonder which definition is running. Commit the project file only when it holds no secrets, and use variables for anything private.

A shared project file has one more benefit: a new teammate clones the repo and gets the same server list without a setup call. Each person then supplies their own tokens through environment variables, so the file stays identical for everyone while the credentials stay personal.

Anatomy of an Entry

Every file has one top-level object called mcpServers. Inside it, each property name is the label of a server, and the value says how to reach it.

A stdio entry uses command, args, env and envFile. A remote entry uses url and headers. Keep the two shapes apart: one entry, one transport.

Your First Server, Step by Step

Four moves handle almost every case: create the file, add an entry, save, then check the result in Settings. The two examples below show a local and a remote entry.

Add a Local Server

1. Create ~/.cursor/mcp.json if it does not exist yet.
2. Paste the entry below.
3. Save the file. Cursor usually picks up the change on its own. If the server does not appear, quit and reopen Cursor.

{
  "mcpServers": {
    "project-files": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
    }
  }
}

Copy Prompt

The -y flag lets npx install the package without asking. The ${workspaceFolder} variable points the server at the open project, so it only reaches files inside that folder.

Add a Remote Server

A remote entry replaces command and args with a url. This example connects GitHub's hosted server and reads the token from an environment variable.

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${env:GITHUB_TOKEN}"
      }
    }
  }
}

Copy Prompt

Servers that support OAuth need no header at all. Cursor opens a browser window the first time you use them, you approve access, and the sign in is stored for later sessions. When a provider hands you a fixed client ID and client secret instead, Cursor accepts an auth object with CLIENT_ID, CLIENT_SECRET and scopes. For the desktop app, register http://localhost:8787/callback as the redirect address.

Variables Keep Secrets Out

Cursor expands these variables inside command, args, env, url and headers:

• ${env:NAME} reads an environment variable.
• ${userHome} is your home directory.
• ${workspaceFolder} is the project root.
• ${workspaceFolderBasename} is the name of the project folder.
• ${pathSeparator} or ${/} gives the right slash for the operating system.

A local server that needs a database address and a script path can combine them:

{
  "mcpServers": {
    "notes-db": {
      "command": "node",
      "args": ["${userHome}${/}tools${/}notes-server${/}index.js"],
      "env": { "DB_URL": "${env:NOTES_DB_URL}" },
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

Copy Prompt

💡 Never paste a real token into a file you commit. Reference an environment variable, and add .env to .gitignore.

Settings, Toggles and Approvals

Open Cursor Settings and look for Tools & MCP. Recent builds also list the same servers under Customize in the sidebar. This is the control room for everything you wrote in mcp.json.

Turn Servers On and Off

Each server has a toggle and a tool count. A healthy one lists its tools. A failing one shows an error state. Three checks tell you the state at a glance:

• The toggle is on.
• The tool count is above zero.
• No error indicator sits next to the name.

Disable servers you do not need for a given task instead of deleting them. The entry stays in the file, and flipping it back on takes a second. It is also the fastest way to cut context load before a long refactor.

Tool Approval and Run Modes

By default Cursor asks for approval before an MCP tool runs. You see the tool name and its arguments, then accept or reject. MCP tools follow the same Run Mode rules as terminal commands, so if your mode runs allowlisted actions immediately, allowlisted MCP tools run immediately too.

💡 Allow read-only tools such as search, list and fetch. Keep approval on for anything that writes, deletes, posts or spends money.

Marketplace Installs in One Click

Writing JSON by hand works, but most people begin with the marketplace. Listings live at cursor.com/marketplace and on cursor.directory.

What Add to Cursor Does

Each listing has an Add to Cursor button. Clicking it opens Cursor, asks you to confirm, and writes the entry into your global ~/.cursor/mcp.json. If the server needs OAuth, Cursor sends you to the provider's sign in page next.

Afterward, open the MCP list and check the tool count. The entry is ordinary JSON, so you can edit it later: rename it, add an env value, or move it into a project file.

Vet Before You Install

A server runs with your permissions, so a one-click install deserves ten seconds of suspicion.

• Check the publisher. Prefer servers from the service itself or from a project with public source code.
• Read the command. npx downloads code from a registry and runs it on your machine.
• Read the tool list. A notes server that asks for shell access is a red flag.
• Pin versions with package@version when stability matters more than updates.
• Prefer remote servers from a provider you already trust and sign in to with OAuth.

If you are unsure what to add first, this short list matches the most common daily tasks:

Fixing a Server That Won't Start

Most failures come from five or six causes. Start with the logs, then match the symptom.

Read the MCP Logs

Open the Output panel with Cmd+Shift+U on Mac or Ctrl+Shift+U on Windows and Linux, then pick MCP Logs from the dropdown. The log records server initialization, tool calls and error messages. Read the first error, not the last one. Later lines are usually side effects.

Six Common Failures

When none of those rows fits, run the server by hand. Copy the command and args from your entry into a terminal, with the same environment values, and watch what it prints. If it fails there, the problem sits in the server or its install, not in Cursor. If it runs fine, compare the terminal's PATH and variables with what Cursor passes through env, and check the log once more for the first line that mentions the server by name.

Pairing MCP With PicassoIA Tools

The connection is only half of the work. Three PicassoIA features help around it.

Drafting and reviewing configs. A Large Language Model can spot a trailing comma, explain an error from the MCP Logs, or turn a README install snippet into a Cursor entry. On PicassoIA you can run Claude Sonnet 5, GPT 5.6 Sol, Kimi K2.6 or Gemini 3.5 Flash from one place and compare how each one reads the same error. Replace every token with a placeholder before you paste a config.

Visuals for docs and READMEs. Setup pages read better with a clear header image. Seedream 4.5, Flux 2 Pro and GPT Image 2 turn a text prompt into a photographic image, and image to video can turn a still into a short clip for a changelog or a social post.

An MCP connection of its own. PicassoIA offers an API at https://api.picassoia.com/v1 and MCP connections managed from your account, spanning image generation, image editing and video generation with audio. Up to five predictions run at once per account, shared across tokens and MCP connections, so a session that fires many requests will queue. The server address is shown inside your account, so this article does not print one. Once you have it, the entry follows the same url shape as the github example above. Check your plan page to confirm which tiers include MCP connections before you build a workflow on it.

Make Your Own Visuals Next

Pick one server from this article, add it today, and approve its first tool call yourself. Then open Picasso IA and generate a header image for your own setup notes: a photo of your desk, a calm background for a diagram, or a short clip for a release post. Try three different prompts, compare the results, and keep the one that fits your page. The full model list is at picassoia.com/en/all-models.