Cursor MCP Server Setup: Connect 87 Tools to Your IDE

Why MCP Matters Inside Cursor

Cursor ships with strong built-in capabilities: file editing, terminal access, codebase search, and web browsing. But real development work often reaches beyond your local repository. You need to query a database, check DNS records, scan for vulnerabilities, look up library documentation, manage deployments, or interact with third-party APIs. Without MCP, each of these requires leaving your editor or pasting results back and forth.

The Model Context Protocol solves this by giving Cursor a standard way to discover and call external tools. When you configure an MCP server, Cursor pulls the tool list on startup. Those tools then appear in Composer (Agent mode), and the AI can decide when to call them based on your request. No plugins, no extensions marketplace, no manual wiring. Just a JSON config and a running server.

Prerequisites

• Cursor version 0.45 or later (MCP support is built in)
• A ToolRoute API key from toolroute.ai (free tier available)
• Agent mode enabled in Composer (this is the default in 2026 versions)

Step 1: Open Cursor MCP Settings

There are two ways to configure MCP servers in Cursor: through the settings UI or by editing a JSON file directly. Both produce the same result.

Option A: Settings UI

Open Cursor Settings with Ctrl+Shift+J (Windows/Linux) or Cmd+Shift+J (macOS). Navigate to the MCPtab in the left sidebar. You will see a list of any existing MCP servers and an "Add new MCP server" button at the top.

In the settings panel, the MCP tab shows all configured servers with their connection status. A green dot means connected. Red means the server is unreachable or the config is invalid.

Option B: Edit mcp.json Directly

Cursor reads MCP configuration from .cursor/mcp.json in your project root for project-scoped servers, or from ~/.cursor/mcp.json in your home directory for global servers. If the file does not exist, create it.

Step 2: Add the ToolRoute Gateway

Rather than configuring individual MCP servers for each tool you need, a gateway lets you access every tool through one endpoint. ToolRoute exposes 87 tools as a single MCP server. One config block, one API key, zero local processes.

If you clicked "Add new MCP server" in the UI, select "HTTP" as the type and paste the URL and headers. If you are editing the JSON file directly, add this block:

{
  "mcpServers": {
    "toolroute": {
      "type": "streamable-http",
      "url": "https://toolroute.ai/mcp",
      "headers": {
        "Authorization": "Bearer tr_live_your_key_here"
      }
    }
  }
}

Replace tr_live_your_key_here with your actual API key. You can generate one from your ToolRoute dashboard.

After saving, the MCP settings panel should show the ToolRoute entry with a green connected indicator. Cursor connects to the gateway on startup and pulls the full tool catalog automatically.

Step 3: Verify the Connection

Back in the MCP settings tab, confirm that "toolroute" shows a green dot. If it shows red or disconnected:

• Check that the URL is exactly https://toolroute.ai/mcp with no trailing slash
• Verify your API key starts with tr_live_ or tr_test_
• Confirm the JSON syntax is valid (no trailing commas, matching brackets)
• Restart Cursor if you edited the file while the app was running

You can also click the refresh icon next to the server name to force a reconnection attempt without restarting.

Step 4: Test a Tool Call in Composer

Open Composer with Ctrl+I (Windows/Linux) or Cmd+I (macOS). Make sure you are in Agent mode (the dropdown at the top of the Composer panel). Then try a request that requires an external tool:

> Look up the Next.js App Router docs for generateStaticParams
  [Cursor calls ToolRoute → Context7 adapter]
  Found 12 documentation sections for generateStaticParams...

> Search for open issues in our GitHub repo about auth
  [Cursor calls ToolRoute → GitHub adapter]
  Found 3 open issues matching "auth"...

> Scan this file for SQL injection vulnerabilities
  [Cursor calls ToolRoute → Semgrep adapter]
  Scanning src/lib/db.ts... 0 findings.

Cursor will show you which MCP tool it is calling and ask for approval before executing. Once you approve, the tool runs through the ToolRoute gateway and the result appears inline in the conversation.

What Tools Are Available?

Through the ToolRoute gateway, Cursor gets access to 87 tools across 14 categories. Here are some of the most useful ones for IDE workflows:

Browse the complete catalog at toolroute.ai/tools.

Project-Level vs Global Configuration

Cursor supports two config file locations:

• Project-level: .cursor/mcp.json in your project root. Only active when that project is open. Good for team-shared configs you can commit to version control (keep your API key in an environment variable if you do this).
• Global: ~/.cursor/mcp.json in your home directory. Active across all projects. Best for personal tool setups like ToolRoute that you want everywhere.

If the same server name appears in both files, the project-level config takes precedence.

Adding Individual MCP Servers Alongside ToolRoute

You can mix the gateway with local MCP servers. If you have a custom internal tool or a self-hosted server, add it alongside the ToolRoute entry:

{
  "mcpServers": {
    "toolroute": {
      "type": "streamable-http",
      "url": "https://toolroute.ai/mcp",
      "headers": {
        "Authorization": "Bearer tr_live_your_key_here"
      }
    },
    "my-internal-api": {
      "command": "node",
      "args": ["./tools/internal-mcp-server.js"]
    }
  }
}

Cursor connects to both servers on startup. The gateway handles the 87 public tools while your local server handles proprietary ones.

Cursor vs Claude Code MCP Setup

If you also use Claude Code, the concepts are identical but the config file differs. Claude Code reads .mcp.json in the project root or home directory. Cursor reads .cursor/mcp.json or uses the settings UI. The ToolRoute gateway URL and API key are the same in both environments. You can run both simultaneously and they share the same tool catalog.

Troubleshooting

Server Shows "Disconnected" in Settings

Cursor validates the MCP connection on startup. If the server appears red or disconnected, check the URL for typos, confirm the API key is valid, and verify your network can reach toolroute.ai. Click the refresh button next to the server entry to retry without restarting Cursor.

Tools Not Appearing in Composer

Make sure you are in Agent mode, not Ask or Edit mode. MCP tools are only available in Agent mode. Also verify that Cursor has finished connecting to the server (the green dot should be solid, not pulsing).

Tool Calls Returning Errors

If a tool call fails, ToolRoute returns a descriptive error message. Common causes: expired API key, insufficient credits, or the target service is temporarily down. Check your key status at toolroute.ai/docs.

JSON Syntax Errors

Cursor silently ignores an invalid mcp.json. If no servers appear after saving, validate your JSON. Common mistakes: trailing commas after the last entry, single quotes instead of double quotes, or missing the outer mcpServers wrapper object.

Frequently Asked Questions

Does Cursor charge extra for MCP tool usage?

No. Cursor does not charge for MCP connections. Tool usage is billed by the tool provider. With ToolRoute, you pay per tool call through prepaid credits. Your Cursor subscription is unaffected.

Can I use MCP tools in Cursor's chat (not Composer)?

MCP tools are available in Composer Agent mode. The inline chat (Ctrl+K / Cmd+K) and the side chat panel do not currently trigger MCP tool calls. Use Composer for tool-integrated workflows.

Is there a limit to how many MCP servers I can configure?

Cursor has no hard limit on configured servers. However, each stdio-based server spawns a local process that consumes memory. Using a gateway like ToolRoute avoids this: one HTTP connection provides access to all 87 tools with zero local processes.

Do MCP servers work with Cursor's free plan?

Yes. MCP support is available on all Cursor plans, including free. The MCP settings tab and Agent mode in Composer are not gated by plan tier.