Cursor MCP: How to Add an MCP Server (mcp.json Guide)

Cursor MCP setup comes down to one file. Add your server under mcpServers in .cursor/mcp.json to use it in one project, or in ~/.cursor/mcp.json to use it in every project. A server entry is either a remote URL with headers or a local command that Cursor starts. Save the file and the server shows up under Customize in Cursor.

Where does Cursor look for mcp.json?

Cursor reads two files, and both have the same shape.

• Project: .cursor/mcp.json at the repo root. Use it for servers tied to one codebase.
• Global: ~/.cursor/mcp.json in your home folder. Use it for tools you want everywhere, such as a docs or search server.

Both files hold a top-level mcpServers object. Each key is a name you choose, and each value describes how to reach that server. If you search for "mcp json cursor" you are looking for exactly this file. A project file can be committed to git, so keep secrets out of it. The global file stays on your machine, but anything you write there is still plain text on disk.

Cursor's docs list three transports: stdio for local servers Cursor runs itself, and SSE and Streamable HTTP for servers reachable by URL, as defined in the MCP specification. Remote servers can serve many users and can sign you in with OAuth. See the Cursor MCP documentation for the full field list.

How do I add a remote MCP server to Cursor?

A remote server needs a url and, usually, a headers block for the key. This is the quickest way to add a Cursor MCP server, because there is nothing to install. The example below points at the MCPifex gateway, which hosts the server for you:

{
"mcpServers": {
"mcpifex": {
"url": "https://mcp.mcpifex.com/mcp",
"headers": {
"Authorization": "Bearer <YOUR_API_KEY>"
}
}
}
}

1. Create a free account at portal.mcpifex.com and set up a server as an instance.
2. Copy your API key from the portal. The API keys and authentication page shows how.
3. Open .cursor/mcp.json or ~/.cursor/mcp.json. Merge the mcpifex entry into mcpServers, with a comma after any existing entry.
4. Replace <YOUR_API_KEY> with your key and save.

The <YOUR_API_KEY> value is a placeholder. Never paste a real key into a file you commit. Cursor expands variables in url and headers, so you can read the key from an environment variable instead:

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

Cursor also supports ${userHome}, ${workspaceFolder} and ${workspaceFolderBasename}. Set MCPIFEX_API_KEY in the shell environment that launches Cursor, or the header will be empty.

One entry reaches every server you set up in the portal. Adding a second or third server happens in the portal, so your mcp.json stays the same size. The Cursor connection page and Cursor and IDE docs have the same snippet with your key filled in once you are signed in.

How do I add a local stdio server?

Many open-source servers run on your machine. Cursor starts the command and talks to it over standard input and output:

{
"mcpServers": {
"my-local-server": {
"command": "node",
"args": ["./mcp-servers/my-server/index.js"],
"env": {
"DATABASE_URL": "postgresql://user:password@host/db"
}
}
}
}

This works, but look at the env block. It holds a database password in plain JSON. In a committed .cursor/mcp.json, anyone with repo access can read it. You can use ${env:NAME} in env values to pull the secret from your shell, or an envFile for stdio servers. Cursor's docs note that stdio servers serve a single user and need manual auth, so every teammate repeats the setup.

A local server also needs its runtime on your machine, such as Node or Python, and you update it yourself. Check that the package is still maintained before you run it. Some early reference servers are archived and get no security fixes.

How do I check that Cursor connected?

Open Customize in Cursor and look for the server there. A working server is listed and loaded. Cursor's docs say a disabled server will not load or appear in chat, so confirm its toggle is on. Then ask the agent to do something the server covers, such as "list the tables in my database", and confirm the answer comes from the right source.

How do I enable tools and approve calls?

There are three separate switches, and it helps to keep them apart.

• Server toggle in Cursor. Each server can be switched on or off under Customize. Off means it does not load.
• Approval in the chat. The Cursor docs state that Cursor asks for approval before using MCP tools by default. You approve a call, or allow that tool to run automatically.
• Tool policy at the server. This one is not part of Cursor. With an MCPifex instance you choose which tools are allowed in the portal. Write and destructive tools start off, and the gateway refuses a tool that is not enabled.

Cursor's approval prompt does not know what a tool does underneath. Approving a tool lets the agent ask, and the server policy decides whether the call goes through. For a database, that means you can turn on query and leave execute off. Our guide on controlling what AI agents can reach covers the idea in more depth.

Is there a limit on MCP tools in Cursor?

Cursor's current MCP page does not state a tool cap. In practice there is still a cost to adding many. Every tool name and description is sent to the model, which can crowd the context and make it pick the wrong tool.

Keep the count down. Turn off servers you are not using in a given project. Prefer a project mcp.json for specialised servers instead of loading all of them globally. With MCPifex, enable only the tools a job needs on each instance. A large server like App Store Connect exposes 88 tools, and 38 of them are write tools that stay off until you enable them.

What if my Cursor MCP server will not connect?

Start with the logs. Cursor's docs say to open the Output panel with Cmd+Shift+U, choose MCP Logs from the dropdown, and look for connection, authentication or crash errors. A failing server does not stop the others from working.

• The server does not appear. The JSON is probably invalid. Check commas between entries and quotes around every key, then reload Cursor.
• A 401 or auth error on a remote server. The key is wrong, revoked or empty. If you used ${env:MCPIFEX_API_KEY}, make sure Cursor was started from a shell where that variable is set.
• A local server crashes. Run its command in a terminal and read the error. A missing runtime or a wrong path is the usual cause.
• The server connects but tools are missing. For a hosted server, check which tools are enabled on the instance. See the troubleshooting docs for gateway errors.
• Changes have no effect. Reload the window after editing mcp.json.

Which MCP servers are worth adding to Cursor?

Start with servers that give the agent something it cannot see in your repo. Five that fit a Cursor workflow:

• PostgreSQL. Lets the agent inspect your schema and run read queries while it writes code against them. On MCPifex the write tool execute is off by default. See the PostgreSQL server page.
• GitHub. Issues, pull requests and repository search from the editor. Read the GitHub MCP server explained.
• Google Search Console. 19 tools for performance data, URL inspection and sitemaps, useful when you work on a site and want real query data. See the Search Console server.
• App Store Connect. Apps, versions, TestFlight, reviews and reports for people who ship iOS apps from Cursor.
• A documentation server such as Context7. Fetches current library docs so the agent stops guessing at API names.

The best MCP servers roundup compares more options, and the MCPifex marketplace lists the servers that are live today.

Why use a hosted gateway instead of many entries?

Every server you add by hand is another mcpServers entry with its own command and its own secrets. More entries mean more places for a credential to leak and more config to keep in sync across a team. With a gateway you keep one entry. Each server is an instance in the portal, where its credentials are saved, masked in the UI, and its tools are switched on or off. MCPifex runs the real server package for you. The MCP server glossary entry explains how an instance relates to the package, and the Claude Code guide shows the same endpoint in another client.

Sources

1. Cursor Docs: Model Context Protocol (MCP)
2. Model Context Protocol: Transports (stdio and Streamable HTTP)
3. Model Context Protocol: Architecture

← Back to guides