Home » MCP Servers » Add to Cursor

How to Add MCP Servers to Cursor IDE

Cursor supports MCP servers through its settings panel and through a JSON configuration file. You can add local stdio servers that run as subprocesses or remote HTTP servers that connect over the network. Once connected, the AI agent in Cursor can invoke your server's tools during conversations.

Before You Start

You need Cursor installed with an active subscription that includes Agent mode. MCP tools are invoked through the Agent, not through the standard chat or edit modes. You also need a working MCP server, either one you built, a community server, or a hosted service.

Step-by-Step Configuration

Step 1: Open Cursor settings.
Open the command palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows/Linux) and type "Cursor Settings" to open the settings panel. Navigate to the MCP section in the left sidebar. This is where all MCP server configurations are managed.

Step 2: Add a new server.
Click the "Add new MCP server" button. Cursor shows a form where you enter the server name and configuration. The name should be descriptive, like "memory" or "database-tools," because it appears in the tool list when the agent considers which tools to use.

Step 3: Configure the transport.
For a local stdio server, enter the command and arguments. For a remote HTTP server, enter the URL and any headers. Cursor's settings form lets you switch between transport types with a dropdown.

You can also configure servers by editing the JSON configuration file directly. Create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "adaptive-recall": {
      "url": "https://mcp.adaptiverecall.com/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    },
    "local-tools": {
      "command": "python",
      "args": ["./tools/server.py"]
    }
  }
}

Step 4: Enable the server.
Each server in the settings panel has a toggle. Make sure it is enabled. Cursor connects to the server when you enable it and disconnects when you disable it. A green indicator means the connection is active. A red indicator means the connection failed, and you can hover over it for error details.

Step 5: Test the tools.
Switch to Agent mode in the Cursor chat panel (the dropdown at the top of the chat). Ask the agent to use a tool from your server. For a memory server, try "What do you remember about this project?" For a search server, try "Search the codebase for authentication logic." The agent should invoke the appropriate tool and return results.

Agent mode required. MCP tools only work in Cursor's Agent mode. The standard Chat and Edit modes do not invoke MCP tools. If you do not see your tools being used, make sure you have Agent selected in the mode dropdown.

Project-Level vs Global Configuration

Cursor supports both project-level and global MCP configuration. Project-level servers are defined in .cursor/mcp.json in the project root and only load when that project is open. Global servers are configured through the Cursor settings panel and load for every project.

Use project-level configuration for servers that are specific to a codebase, like a custom file analyzer or a project database connector. Use global configuration for servers you want everywhere, like a memory system that persists across all your projects.

Troubleshooting

Server shows red indicator: The connection failed. Check the error message by hovering over the indicator. Common causes: the command is not found (wrong PATH), the server crashes during startup (missing dependencies), or the URL is unreachable (network or firewall issue).

Server connects but tools are not used: The agent might not recognize when to use your tools based on the conversation. Try explicitly asking it to use a specific tool by name. If the tool is still not invoked, check whether the tool descriptions in your server are clear enough for the model to match them to the request.

Tools work sometimes but not reliably: The AI model decides when to use tools based on the conversation context and tool descriptions. If your tool descriptions are too vague, the model may not consistently select them. Improve the descriptions in your MCP server to be more specific about when and why the tool should be used.

Environment variables not available: Stdio servers inherit the environment from Cursor, which may not include your shell profile, virtual environment activations, or custom PATH entries. Specify required environment variables in the configuration's env field, or use absolute paths for commands.

Working with Multiple Servers

Cursor can connect to multiple MCP servers simultaneously. Each server's tools appear in the same agent tool palette, and the agent can invoke tools from different servers within a single conversation. This lets you compose capabilities: a memory server for persistent recall, a database server for queries, and a search server for codebase exploration all work together through the agent.

Keep tool names unique across servers. If two servers register a tool with the same name, the behavior is undefined and the agent may call the wrong one. Use descriptive prefixes in your tool names if there is any risk of collision.

Give Cursor persistent memory across sessions. Connect Adaptive Recall and your AI coding assistant remembers your codebase, decisions, and patterns.

Get Started Free