Model Context Protocol (MCP) lets Cursor Agent call external tools and read approved data sources. An MCP server might expose documentation search, issue tracking, a browser, or an internal service. The connection expands what Agent can do, so configuration, credentials, and tool approval deserve the same review as any other development dependency.

Decide whether MCP is necessary

Use MCP when Agent needs a repeatable interface to an external system. Do not add a server merely because it is popular. Before installation, answer:

  • What exact task requires this server?
  • Who publishes and maintains it?
  • Which tools, files, network destinations, or accounts can it access?
  • Can it mutate data, or is it read-only?
  • How will credentials be stored and rotated?
  • How can the server be disabled and audited?

For a one-off public fact, a reviewed link may be safer than a persistent tool connection.

Choose project or global configuration

Cursor’s current MCP documentation supports two common configuration locations:

<project>/.cursor/mcp.json   # Shared project configuration
~/.cursor/mcp.json          # Personal configuration across projects

Project configuration is appropriate for a tool the repository expects every contributor to use. Review it in code review before committing. Global configuration is better for personal tools and account-specific integrations. Cursor merges the two; current documentation says a project server takes priority when the same name appears in both.

Configure a local stdio server

A local server is launched by a command. The exact executable and arguments must come from the server’s trusted documentation. This safe-shaped example uses environment interpolation instead of a literal key:

{
  "mcpServers": {
    "project-docs": {
      "command": "node",
      "args": ["${workspaceFolder}/tools/docs-server.mjs"],
      "env": {
        "DOCS_TOKEN": "${env:DOCS_TOKEN}"
      }
    }
  }
}

Cursor documents variables such as ${workspaceFolder}, ${userHome}, and ${env:NAME} for supported configuration fields. Keep the real secret in the operating-system or shell environment, exclude local secret files from Git, and restart Cursor if the desktop process does not see a newly added variable.

Configure a remote server

A hosted MCP server uses a URL and may require authentication:

{
  "mcpServers": {
    "team-service": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:TEAM_MCP_TOKEN}"
      }
    }
  }
}

Replace the example only with a URL supplied by the service owner. Confirm TLS, data residency, logging, retention, and account scope before sending proprietary context. Do not paste bearer tokens directly into a committed mcp.json.

Enable and verify the server in Cursor

  1. Open Customize → MCPs.
  2. Find the configured server and confirm its source and connection state.
  3. Enable it if it is disabled.
  4. Inspect the available tool names and descriptions.
  5. Start with a read-only request that names the intended tool.
  6. Review the arguments before approving the call.
  7. Confirm that the response contains only the expected data.

Cursor asks for approval before MCP tool use by default. Current Run Mode and organization policies can change that behavior, so never assume a tool will always pause. Keep the allowed set narrow, especially for tools that write files, send messages, query production data, or trigger deployments.

Test with a bounded prompt

Use a request that limits the system, operation, and output:

Use the project-docs MCP server only.
Search for the documented local test command and return the source page title.
Do not edit files, run terminal commands, or call any write-capable tool.

Then compare the answer with the original source. A connected status proves only that Cursor can communicate with the server; it does not prove that tool results are correct or safe.

Protect credentials and sensitive data

  • Reference environment variables instead of committing tokens.
  • Give the integration the least privilege and shortest practical token lifetime.
  • Separate development and production accounts.
  • Do not expose .env, private keys, customer records, or unrestricted database tools.
  • Review tool arguments and returned content for prompt injection or unexpected secrets.
  • Revoke credentials when a machine, contributor, or integration is removed.

An MCP server executes outside the language model. Cursor’s approval interface is a useful checkpoint, but it is not a substitute for server-side authorization, audit logs, backups, and network controls.

Troubleshoot Cursor MCP

The server is disconnected

Open Cursor’s Output panel and select MCP logs. Check the executable path, arguments, working directory, required runtime, and whether the desktop process can read the required environment variables.

The server connects but exposes no tools

Confirm that the server implements supported MCP capabilities and has completed its startup handshake. Check server logs without printing credentials.

A remote server returns an authentication error

Verify the environment variable name, token scope, expiry, and server URL. Rotate a token if it was ever pasted into chat, logs, or source control.

The wrong configuration wins

Look for the same server name in both project and global mcp.json. Rename servers clearly and remove stale duplicates rather than relying on accidental precedence.

Agent calls a tool too freely

Disable the server, reduce its permissions, and review Cursor’s current approval or permissions.json controls. Avoid blanket approval for a server with mixed read and write tools.

Pair tools with maintained rules

Once the connection is verified, document when the project expects the tool to be used and what checks must follow. The Cursor Rules tutorial explains how to keep that guidance scoped and version-controlled. Rules guide Agent; the MCP server and its account permissions still enforce the real boundary.

Published
Information verified
By
AI Tool Blog Editorial Team