Cursor mcp.json: Complete Configuration Guide

Cursor uses mcp.json to discover and connect to Model Context Protocol servers.

The file tells Cursor which servers are available, whether they should be launched as local processes or reached through remote endpoints, and which commands, arguments, URLs, or environment variables are required for the connection.

A correctly configured mcp.json file allows Cursor Agent to use external tools and data sources directly within its workflow. Depending on the MCP server, this may include development tools, databases, documentation systems, issue trackers, browser automation, or internal services.

This guide explains where Cursor stores mcp.json, how the file is structured, how to configure local and remote servers, and how to avoid common configuration and security mistakes.

Quick Answer

Create .cursor/mcp.json in a repository for project-specific MCP servers or ~/.cursor/mcp.json for servers that should be available globally. Add each server as a named entry inside the top-level mcpServers object.

What Is Cursor mcp.json?

mcp.json is Cursor's configuration file for custom MCP servers.

At its simplest, the file contains a top-level mcpServers object. Each property inside that object represents a separately configured server.

A basic local configuration looks like this:

json

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"]
    }
  }
}

In this example:

mcpServers contains all configured MCP server definitions.
server-name is the identifier assigned to the server.
command tells Cursor which executable to launch.
args contains the arguments passed to that executable.

The server name does not launch anything by itself. It is a readable identifier that helps Cursor and the user distinguish one configured server from another.

A single file can contain multiple server definitions:

json

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "documentation-mcp-server"]
    },
    "project-tools": {
      "command": "node",
      "args": ["./tools/mcp-server.js"]
    }
  }
}

Each server is configured independently, allowing one Cursor project to use several MCP integrations at the same time.

Where Is Cursor mcp.json Located?

Cursor supports two official configuration locations:

text

                         Cursor
                            │
             ┌──────────────┴──────────────┐
             ▼                             ▼
     Project configuration          Global configuration
      .cursor/mcp.json                ~/.cursor/mcp.json
             │                             │
             ▼                             ▼
   Current repository only          Available everywhere
             └──────────────┬──────────────┘
                            ▼
                       MCP Servers

Project Configuration

For a project-specific setup, create:

text

.cursor/mcp.json

The path is relative to the root of the repository:

text

my-project/
├── .cursor/
│   └── mcp.json
├── src/
├── package.json
└── README.md

Project configuration is useful when an MCP server belongs to one repository or should be shared with developers working on that project.

Typical examples include:

a repository-specific documentation server
a development database integration
internal tools associated with one application
an MCP server launched from a script stored in the repository

Because project files may be committed to version control, do not place real secrets directly inside a shared mcp.json.

Global Configuration

For MCP servers that should be available across projects, create:

text

~/.cursor/mcp.json

The tilde represents the current user's home directory.

A global configuration is appropriate for personal tools or integrations used in many repositories.

Examples may include:

a general-purpose local utility
a personal knowledge source
a commonly used development integration
an MCP server that is not tied to one codebase

Global configuration avoids copying the same server definition into every project.

Project vs Global mcp.json

The main difference is scope.

Configuration	Location	Scope	Best for
Project	`.cursor/mcp.json`	Current repository	Project-specific and team-shared tools
Global	`~/.cursor/mcp.json`	All Cursor projects	Personal or reusable integrations

Use project configuration when the MCP server is part of the repository's development workflow.

Use global configuration when the server should remain available regardless of which project is open.

Before sharing a project-level file, review it for:

API keys
access tokens
passwords
private URLs
machine-specific absolute paths
user-specific commands

A configuration that works on one computer may fail for another developer when it contains paths or dependencies that exist only on the original machine.

Want to analyze your API security?

Import your OpenAPI spec and generate a Security Report automatically.

Understanding the mcp.json Structure

The root of a standard Cursor MCP configuration contains mcpServers:

json

{
  "mcpServers": {}
}

Each key inside that object identifies one server:

json

{
  "mcpServers": {
    "first-server": {},
    "second-server": {}
  }
}

The properties inside a server definition depend on how Cursor connects to it.

A local stdio server typically uses:

command
args
env

A remote server uses a URL pointing to its MCP endpoint.

Conceptually, the configuration works like this:

text

                    mcp.json
                       │
                       ▼
                  mcpServers
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
      Local server  Remote server  Another server
          │            │            │
       command         URL         configuration
       arguments
       environment
          └────────────┴────────────┘
                       │
                       ▼
                     Cursor

The JSON must remain syntactically valid. Common JSON mistakes include:

missing commas
trailing commas
unquoted property names
mismatched braces
comments inside standard JSON
duplicated server names

Configuring a Local stdio Server

The stdio transport is commonly used for local MCP servers.

With stdio, Cursor launches the configured server as a subprocess. MCP messages are then exchanged through the process's standard input and standard output streams.

A Node.js-based server can be configured like this:

json

{
  "mcpServers": {
    "local-node-server": {
      "command": "npx",
      "args": ["-y", "mcp-server"]
    }
  }
}

A Python-based server may use a Python command and script path:

json

{
  "mcpServers": {
    "local-python-server": {
      "command": "python",
      "args": ["./servers/example_server.py"]
    }
  }
}

The exact executable name can depend on the operating system and local installation. For example, a system may expose Python as python, python3, or through a package runner.

The connection flow is:

text

             Cursor
                │
                │ launches command
                ▼
        Local MCP process
                │
       stdin ◄──┼──► stdout
                │
                ▼
        Tools and resources

For stdio to work correctly:

The executable must be installed and available.
The script or package must exist.
The arguments must be valid.
The server must start without immediately crashing.
The server must reserve stdout for valid MCP messages.

Diagnostic logs should be written to stderr rather than mixed into the MCP messages sent through stdout.

Using Arguments in mcp.json

The args property is an array. Each argument should be entered as a separate string.

Correct:

json

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "mcp-server", "--mode", "development"]
    }
  }
}

Avoid combining multiple arguments into one string unless the launched command explicitly expects that exact value:

json

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y mcp-server --mode development"]
    }
  }
}

The second version may be interpreted as one argument rather than four separate arguments.

Keeping arguments separated makes the process invocation clearer and reduces platform-specific quoting problems.

Adding Environment Variables

Cursor allows environment variables to be passed to a locally launched MCP server through the env object.

The official configuration pattern is:

json

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

Each property inside env becomes an environment variable available to the launched server process.

Environment variables may be used for:

API credentials
service endpoints
feature flags
database configuration
runtime modes

However, placing a real secret directly in mcp.json does not automatically make it secure.

For example:

json

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "example-mcp-server"],
      "env": {
        "API_KEY": "real-production-secret"
      }
    }
  }
}

This becomes dangerous when the file is committed, copied, logged, included in a support request, or shared with another person.

Treat any secret written directly into a configuration file as sensitive data and prevent it from entering version control.

Learn more in Cursor MCP Environment Variables.

Configuring a Remote MCP Server

Not every MCP server runs on your local machine.

Many organizations deploy MCP servers on dedicated infrastructure, making them available over the network. Cursor can connect to these remote servers using supported MCP transports.

Modern MCP deployments typically use Streamable HTTP, while SSE (Server-Sent Events) is supported primarily for compatibility with older implementations.

A simplified remote configuration looks like this:

json

{
  "mcpServers": {
    "remote-server": {
      "url": "https://example.com/mcp"
    }
  }
}

Unlike local stdio servers, Cursor does not start a remote process. Instead, it connects to the configured MCP endpoint and exchanges protocol messages over the network.

The communication flow is:

text

              Cursor
                 │
             HTTPS
                 │
                 ▼
         Remote MCP Server
                 │
                 ▼
      Tools • APIs • Databases

Remote deployments are particularly useful when:

multiple developers need access to the same MCP server
tools run inside cloud infrastructure
integrations require centralized authentication
internal company services should be shared across teams

When using remote servers, always use HTTPS whenever possible and ensure the server implements appropriate authentication and authorization controls.

Configuring Multiple MCP Servers

One of the biggest advantages of mcp.json is that a single configuration file can contain multiple independent MCP servers.

For example, one server might provide access to documentation, another to an issue tracker, and a third to internal developer tools.

json

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "documentation-server"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "github-server"]
    },
    "internal-tools": {
      "url": "https://example.com/mcp"
    }
  }
}

Cursor treats each entry as an independent MCP server.

This modular approach makes configuration easier to maintain because each server can be updated, replaced, or removed without affecting the others.

As projects grow, organizing servers with clear, descriptive names also improves readability for everyone working on the repository.

Cursor Agent CLI and mcp.json

The same mcp.json configuration used by the Cursor editor is also recognized by Cursor Agent CLI.

This means you generally do not need to maintain separate MCP configurations for graphical and command-line workflows.

When the CLI starts inside a project, it automatically discovers the applicable MCP configuration and makes the configured servers available to the agent.

Using a shared configuration offers several benefits:

consistent behavior between the editor and CLI
fewer duplicated configuration files
simpler onboarding for new developers
easier maintenance as projects evolve

Keeping a single source of truth for MCP configuration reduces the risk of inconsistencies between development environments.

Common mcp.json Mistakes

Most configuration problems are caused by small mistakes rather than issues with Cursor itself.

Invalid JSON

Because mcp.json uses standard JSON syntax, even a single missing comma or unmatched brace can prevent the file from being parsed correctly.

Always validate the file after making changes.

Incorrect File Location

Cursor only discovers mcp.json when it is placed in the correct location.

Using the wrong directory is one of the most common reasons why configured servers fail to appear.

Missing Executables

For stdio servers, the configured command must exist on the local machine.

If the executable cannot be found, Cursor will be unable to launch the server.

Incorrect Arguments

Passing invalid command-line arguments can prevent an otherwise valid server from starting.

Always verify the startup instructions provided by the MCP server's documentation.

Server Startup Failures

Even with a correct configuration, an MCP server may fail during initialization because of missing dependencies, runtime errors, or unavailable external services.

Checking the server logs is often the fastest way to identify these problems.

Mixing Secrets with Shared Configuration

Project-level configuration files are frequently committed to version control.

Avoid placing production API keys or other sensitive credentials directly inside files that may be shared with other developers.

Security Best Practices

A well-structured mcp.json file improves maintainability, but security should always be part of the configuration process.

Whether you're connecting to local development tools or production services, following a few best practices can help protect your environment and reduce operational risks.

Keep Secrets Out of Version Control

Avoid committing production credentials directly to mcp.json.

If a project requires authentication, use environment variables, secret management solutions, or other secure credential storage mechanisms instead of hardcoding sensitive values.

Before pushing changes to a shared repository, review the configuration for:

API keys
access tokens
passwords
private endpoints
internal URLs

Use the Principle of Least Privilege

Configure each MCP server with only the permissions it actually requires.

For example, if a server only needs read access to documentation, it should not also have permission to modify production resources.

Limiting permissions reduces the impact of configuration mistakes and compromised credentials.

Review Third-Party MCP Servers

An MCP server can expose powerful capabilities to Cursor.

Before adding a third-party server to your configuration:

verify its source
review its documentation
understand which tools it exposes
understand which external systems it can access

Only install MCP servers that you trust.

Separate Development and Production

Whenever possible, use separate configurations or credentials for:

local development
testing
staging
production

This reduces the chance of accidentally running development tools against production infrastructure.

Keep Dependencies Updated

Many local MCP servers depend on external packages or runtimes.

Regularly updating those dependencies helps:

receive security fixes
improve compatibility
reduce known vulnerabilities
ensure support for newer MCP features

Configuration maintenance should be considered an ongoing task rather than something performed only during the initial setup.

Conclusion

The mcp.json file is the foundation of custom MCP server configuration in Cursor.

Whether you are launching local stdio servers or connecting to remote deployments over HTTP, this single configuration file tells Cursor how to discover and communicate with external capabilities.

A well-organized mcp.json makes projects easier to maintain, simplifies collaboration, and helps create a consistent development experience across both the Cursor editor and Cursor Agent CLI.

As your MCP ecosystem grows, keeping configurations modular, validating changes carefully, and following security best practices will make your integrations more reliable and easier to manage.

Continue learning:

Cursor MCP Config — Learn how Cursor configuration works as a whole.
Cursor MCP stdio — Understand local MCP server communication.
Cursor MCP HTTP Transport — Explore remote MCP deployments.
Cursor MCP Environment Variables — Manage configuration values and credentials securely.
Cursor MCP Authentication — Learn how MCP servers authenticate users and services.
Cursor MCP Servers — Discover how MCP servers extend Cursor with tools, resources, and integrations.

Cursor mcp.json: Complete Configuration Guide