Cursor MCP Setup: mcp.json Format & Locations (2026)

Cursor MCP setup: project and global mcp.json in six steps

To configure MCP in Cursor, create .cursor/mcp.json inside the repository for a project-specific server or ~/.cursor/mcp.json for a server available across workspaces. Add the local command or remote URL under mcpServers, then open Cursor Settings → Tools & MCP to enable the server and verify its tools.

Cursor also supports Marketplace plugins and centrally distributed Team MCPs. For a custom server, the shortest reliable path is to choose the correct configuration scope, add one server, verify its tools, and run a read-only test before enabling writes.

For a custom server:

1. Create .cursor/mcp.json in the project or ~/.cursor/mcp.json for a global setup.
2. Add a local command or remote MCP URL under mcpServers.
3. Open Cursor settings and find Tools & MCP.
4. Enable the server and complete OAuth if the provider requests it.
5. Confirm that the server is connected and its tools appear under Available Tools.
6. Ask Cursor to perform a small read-only test before enabling write actions.

Project configuration is usually the safer default for a database, internal API, or repository-specific service. Global configuration is useful for tools needed in almost every workspace.

If a database or API credential should not be copied into mcp.json, compare the local-server path with a hosted MCP gateway. datamcp currently supports PostgreSQL, MySQL, and OpenAPI or Swagger sources, plus hosted Agent Memory for shared project context.

What is MCP in Cursor?

The Model Context Protocol lets Cursor connect its agent to external tools and data sources. An MCP server can expose:

• tools that Cursor may call
• resources that provide contextual data
• prompts that provide reusable workflows

MCP clients can also provide capabilities to servers. For example, roots describe filesystem boundaries supplied by the client, while elicitation lets a server request additional user input through a supporting client. These are not server-side data sources by themselves.

Cursor lists connected MCP tools under the agent's available tools and selects them when they are relevant to the request. The server, authentication method, and upstream system still determine what the tool is allowed to read or change.

MCP is not a permission system by itself. Connecting a server can give an agent access to a repository, browser session, workspace, payment account, or production database. Review the server's effective permissions before treating installation as a harmless editor preference.

How to add an MCP server to Cursor

1. Install through Cursor Marketplace or Customize

The current Cursor Marketplace provides plugins that can bundle MCP servers with skills, rules, commands, agents, and hooks. Cursor's Customize surface also lets users manage MCPs and other agent extensions in one place.

Use the Marketplace when an official provider plugin already exists and its complete bundle matches the workflow. One-click installation reduces JSON mistakes and can start the provider's authentication flow directly.

Marketplace inclusion does not mean every tool should be enabled. Check whether the plugin includes write or administration tools after installation.

2. Add a custom server with mcp.json

Use mcp.json for a local package, a self-hosted server, or a remote endpoint that is not installed through the directory.

Cursor documents two configuration locations:

Do not commit credentials inside a project-level file. If a team shares .cursor/mcp.json, keep secrets in environment variables or use an OAuth-enabled remote server.

3. Use Team MCPs or team marketplaces

Current Cursor versions support Team MCPs and team marketplaces. Admins can configure approved MCP servers once and distribute them across cloud agents, the agents window, the IDE, and the CLI. Organization groups can narrow access to team marketplace content.

This is useful when an organization wants one reviewed configuration instead of asking every developer to paste a server definition and choose permissions independently.

Cursor mcp.json format

The root object is mcpServers. Each key is the name Cursor displays for that server.

Local stdio MCP server

A local server starts as a child process on the developer machine:

{
  "mcpServers": {
    "example-local": {
      "command": "npx",
      "args": ["-y", "example-mcp-package"],
      "env": {
        "EXAMPLE_API_KEY": "YOUR_LOCAL_SECRET"
      }
    }
  }
}

Use a local server when the package must access local files, a local browser, or a development service. The machine must have the required runtime, and the developer or team owns package updates. Do not commit a real secret in this example; use a local ignored configuration, wrapper command, or secret-injection workflow supported by your environment.

Remote HTTP MCP server

A remote server is identified by a URL:

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

If the server supports OAuth, Cursor can open an authentication flow. Some remote servers instead require an authorization header:

{
  "mcpServers": {
    "example-remote": {
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Prefer OAuth or environment-backed secrets over committing a bearer token. A hosted endpoint removes local process maintenance but still sends requests and selected context to the server operator.

Real Cursor MCP configuration examples

GitHub MCP Server

GitHub's hosted remote server is the recommended option for most users. In compatible Cursor versions, install it through the MCP directory and complete OAuth.

The official remote endpoint is:

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

GitHub also maintains a local GitHub MCP server for teams that need customization or a specific deployment model. Restrict OAuth scopes or personal access token scopes and disable toolsets that the workflow does not require.

Playwright MCP

Playwright MCP runs locally by default and gives Cursor structured browser automation tools:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Use an isolated browser profile when the agent should not inherit unrelated authenticated sessions.

Figma MCP

Figma recommends its hosted remote server for most users:

{
  "mcpServers": {
    "figma": {
      "url": "https://mcp.figma.com/mcp"
    }
  }
}

Complete the Figma OAuth flow after adding it. Figma also provides a desktop server for specific local and organization workflows. Use the official Figma MCP documentation rather than old third-party package names.

Notion MCP

Notion's actively maintained server is hosted and OAuth-based:

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

The connected agent receives access based on the authorizing Notion user. Review that user's workspace access before enabling write workflows.

Linear MCP

Linear provides a hosted Streamable HTTP server:

{
  "mcpServers": {
    "linear": {
      "url": "https://mcp.linear.app/mcp"
    }
  }
}

Authenticate with Linear and verify whether the agent may only read issues or also create and update them.

For more choices, see Best MCP Servers for Cursor and Claude Code.

Cursor PostgreSQL MCP mcp.json configuration

There are two main architectures.

Local PostgreSQL MCP server

A local server runs on the developer machine and usually receives the PostgreSQL connection string through its arguments or environment. This is simple for a local development database but distributes the database credential to every machine that needs the connection.

Use the PostgreSQL MCP server comparison to evaluate current local, provider-specific, and hosted options. The old @modelcontextprotocol/server-postgres reference package is deprecated and archived; existing configurations should follow the migration guide rather than only swapping package names.

Hosted PostgreSQL MCP link

datamcp stores the PostgreSQL connection server-side and gives Cursor a remote MCP endpoint:

{
  "mcpServers": {
    "app-database": {
      "url": "https://api.datamcp.app/api/mcp/YOUR_CONNECTION_ID",
      "headers": {
        "Authorization": "Bearer YOUR_DATAMCP_API_KEY"
      }
    }
  }
}

Full disclosure: datamcp is our product.

The database credential does not appear in mcp.json. Each MCP link can use read-only, read-write, full-access, or custom table-level operations, while the connected PostgreSQL role remains the outer permission boundary. Links can be revoked individually and PostgreSQL query activity is available for review.

datamcp also supports OpenAPI 3.x connections and hosted Agent Memory, but it does not offer a self-hosted edition or provider-administration tools. If local-only operation or provider administration is the main requirement, use a local or provider-specific server instead.

Follow the Cursor PostgreSQL setup tutorial or Cursor MySQL MCP tutorial for the full database sequence. If the database runs on Supabase, use the Supabase MCP server guide to choose between the official platform server and a database-focused PostgreSQL connection.

For cross-chat project context, the same remote URL format can connect Cursor to datamcp Agent Memory. The Cursor memory guide compares native Memories, Rules, file-based Memory Banks, and hosted MCP memory. The agent memory guide explains the search, append, and handoff workflow, while the Memory Bank MCP comparison covers file-based alternatives.

Create one hosted connection and MCP link for free. To use the same database through a separately governed ChatGPT app, follow the ChatGPT PostgreSQL MCP guide.

The Cursor PostgreSQL integration page explains the hosted product path, permissions, credential isolation, and comparison with a local PostgreSQL MCP process.

How to verify an MCP server in Cursor

After installation:

1. Open Cursor settings.
2. Go to Tools & MCP.
3. Confirm that the server is enabled and connected.
4. Expand the server and inspect its available tools.
5. Complete OAuth or correct the local command if Cursor reports an authentication or startup error.
6. Ask for a narrow read-only test, such as listing repository metadata, reading one issue, or inspecting database schema.
7. Review the proposed tool call before allowing a write action.

Cursor's agent uses available MCP tools when they are relevant. If selection is ambiguous, name the server or desired action explicitly in the prompt: “Use the Linear MCP to read ENG-427” is easier to verify than “find the ticket.”

Does Cursor have a 40-tool MCP limit?

Older Cursor MCP guides commonly repeat a hard 40-tool limit. Do not use that number as a current planning rule.

Cursor's current MCP documentation does not publish a universal 40-tool cap. Current Cursor releases expose context-usage information and let users enable or disable MCP servers. The practical limit depends on the model, tool descriptions, other context, and the agent surface being used.

The underlying advice still matters: install focused servers and disable tool groups you do not use. A smaller tool surface is easier for the model to select correctly and easier for a human to review.

Cursor MCP troubleshooting

Server does not appear

• Confirm the file is exactly .cursor/mcp.json or ~/.cursor/mcp.json.
• Validate the JSON and remove trailing commas.
• Confirm the root key is mcpServers.
• Check that the server is enabled in Tools & MCP.

Local server fails to start

• Run the configured command directly in a terminal.
• Confirm node, npx, uvx, Docker, or another required runtime is installed.
• Use an absolute executable path if Cursor cannot resolve the shell environment.
• Pin a known package version when latest introduces an incompatible change.

Remote server returns 401 or 403

• Reconnect OAuth if the provider session expired.
• Confirm the URL matches the provider's official endpoint.
• For bearer authentication, include the Bearer prefix.
• Verify that the token, MCP link, project, or organization is still active.
• Check provider-side policies that may block the client or requested scope.

Server connects but tools are missing

• Inspect whether the provider uses optional toolsets or feature groups.
• Check read-only, project, repository, or category filters.
• Confirm that the authenticated account can access the target resource.
• Disable and re-enable the server after changing its configuration.

Cursor does not call the expected tool

• Name the MCP server and action explicitly.
• Remove overlapping servers that expose near-identical tools.
• Check the agent's available tools before prompting.
• Split a broad request into a read step and a separate write step.

Security checklist for Cursor MCP servers

Before connecting a real system:

• install from the provider's official domain or verified repository
• prefer project scope for project-specific access
• use OAuth or environment variables instead of committed secrets
• start with read-only tools and a non-production resource
• restrict repository, project, table, or account scope where supported
• review tool calls before writes or destructive operations
• verify how to revoke one client without rotating every credential
• confirm where activity can be reviewed
• keep local packages pinned and updated
• treat browser profiles and local files as sensitive resources

For deeper permission design, read MCP authorization, permissions, and scopes and the production MCP security checklist.

Cursor MCP FAQ

Where is Cursor's mcp.json file?

Use .cursor/mcp.json inside a repository for project-specific servers. Use ~/.cursor/mcp.json in the user's home directory for servers that should be available across workspaces.

How do I add an MCP server to Cursor?

Install a suitable Marketplace plugin, add a custom local or remote server under the mcpServers key in mcp.json, or use an organization-distributed Team MCP. Then open Cursor's MCP settings, authenticate if required, and verify the available tools.

Does Cursor support remote MCP servers?

Yes. Add the remote MCP URL to mcp.json. The server may use OAuth or another supported authentication mechanism such as an authorization header. Confirm the provider's current endpoint and never copy backend credentials into the configuration when a scoped client credential is available.

Should a database MCP server be project or global?

Project scope is usually the safer default because the server appears only in the repository that needs it. A global database server can become available in unrelated workspaces, increasing the chance of using the wrong environment or data source.

Why does Cursor connect but show no MCP tools?

Check the authenticated account, project or repository scope, optional tool groups, read-only settings, and server logs. After changing configuration, disable and re-enable the server or restart Cursor so it refreshes discovery.