Adding an MCP Server to Cursor: mcp.json Setup Guide

To add an MCP server to Cursor, put an entry under mcpServers in a file called mcp.json. Use .cursor/mcp.json in your repo for one project, or ~/.cursor/mcp.json in your home folder for every project. An entry is either a local command Cursor starts or a remote URL it calls over HTTP.

Add a hosted server in one block

This is the quickest route. It points Cursor at the MCPifex gateway, so there's no process to run and no server credential in the file:

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

Merge the mcpifex entry into the mcpServers object of either file, with a comma after any existing entries. Replace <YOUR_MCPX_KEY> with a key from the portal, then reload Cursor. See API keys and authentication for how to generate one.

The key is the only secret in the file. If the file leaks, you revoke one key, and no database password or service token is exposed.

Project or global file?

.cursor/mcp.json applies only inside that project. Use it for servers tied to one codebase. ~/.cursor/mcp.json applies to every project, which suits tools you always want, like a search or docs server. If the same name appears in both, the project entry wins in that workspace.

Both files have the same shape: a top-level mcpServers object, keyed by a name you choose. Each value is either a command and args block, or a type: "http" block with a url.

Add a local, command-based server

Servers you install yourself usually run as stdio processes. Cursor runs a command and talks to the server over stdin and stdout:

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

Look at what's in that file: a full connection string with the password, in plain JSON. If .cursor/mcp.json is committed, anyone who can read the repo can read the password. The global file avoids the repo problem, but the secret is still unencrypted on disk, and each teammate has to copy the same block.

Also check that a package is still maintained before you run it this way. Some early reference servers have been archived, and an unmaintained server gets no security fixes.

Check that it connected

Open Settings → MCP after saving. A working server shows as connected, with its tool count. A broken one shows an error you can expand to see the stderr or HTTP response.

Then ask Cursor's agent to do something the server's tools cover, and confirm it reaches the right data. The PostgreSQL server page lists the tools an instance exposes.

How tool approval works

The first time an agent calls a tool from a server, Cursor asks for approval. You can allow it once or mark the tool to run automatically. That gate lives in Cursor and doesn't know what the tool does underneath.

Servers on MCPifex have a second gate. Each instance's tools are switched on or off in the portal, write and destructive tools start off, and the gateway refuses any call to a tool that isn't enabled. Approving a tool in Cursor only lets the agent ask.

If it doesn't connect

• The server doesn't appear: check the JSON is valid, especially commas between entries, then reload Cursor.
• An HTTP error in Settings → MCP: a 401 means the key is wrong or revoked. Generate a new one and update the header.
• A local server fails: run its command in a terminal to see the error. Missing Node or a wrong path is the usual cause.
• Tools are missing: for a hosted server, check which tools are enabled on the instance.

One block instead of one per server

Every server you add by hand is another mcpServers entry with its own command and its own secrets. Each extra server adds another credential to files that could leak, and each one has to be kept in sync across a team. As of September 2026, Cursor's mcp.json has no way to fan one entry out to many servers.

The MCPifex marketplace works differently. You keep one entry pointing at the gateway and set up each server as an instance in the portal, where its credentials and tool switches live. Your mcp.json doesn't grow as you add servers. See the MCP server glossary entry for how an instance relates to the server package.