How to Use AI Agent Tools with Cursor: MCP Setup Guide

Cursor has quickly become the IDE of choice for AI-assisted development. Its tight integration with language models makes it powerful out of the box, but there is a way to make it dramatically more capable: MCP servers.

MCP (Model Context Protocol) servers extend what Cursor's AI can do. Instead of being limited to code completion and chat, Cursor with MCP can query databases, search documentation, interact with APIs, manage files, and run specialized tools — all without leaving your editor.

This guide walks you through the complete setup process: understanding what MCP support means in Cursor, installing your first MCP server, configuring the connection, and troubleshooting the issues that trip up most developers.

What MCP Support Means in Cursor

Cursor added MCP support to give its AI assistant access to external tools. When you configure an MCP server, you are telling Cursor: "Here is a running tool server. When the AI needs to perform actions beyond code generation, it can call tools on this server."

In practical terms, this means:

• The AI can use tools — query a database, fetch a URL, search a codebase index, or call an API
• Tools appear in the agent panel — you can see which tools are available and what they do
• Tool calls are visible — when the AI uses a tool, you see the input and output in the chat
• You stay in your editor — no switching to a terminal or browser to run auxiliary tasks

MCP servers in Cursor work in the agent mode (Cmd+I or Ctrl+I). When you open the agent panel and ask a question that requires external action, Cursor's AI will automatically select and call the appropriate MCP tool.

Prerequisites

Before setting up MCP in Cursor, make sure you have:

• Cursor 0.45 or later — MCP support was introduced in this version. Check your version in Help > About.
• Node.js 18+ — most MCP servers are distributed as npm packages or run via npx
• Python 3.9+ — some MCP servers (especially those from AgentNode) are Python-based
• A terminal — you will need to run some commands outside Cursor for initial setup

Step 1: Understanding Cursor's MCP Configuration

Cursor stores MCP server configurations in a JSON file. There are two locations:

Project-level (recommended)

Create a .cursor/mcp.json file in your project root. This configuration is scoped to the current project and can be committed to version control so your team shares the same tools.

Global-level

Create a ~/.cursor/mcp.json file in your home directory. This configuration applies to all projects.

The configuration file follows this structure:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "env": {
        "API_KEY": "your-api-key-here"
      }
    }
  }
}

Each entry in mcpServers defines one MCP server. The key (server-name) is a label you choose. The command and args tell Cursor how to start the server. The optional env object passes environment variables.

Step 2: Installing Your First MCP Server

Let's start with a practical example. We will install a filesystem MCP server that gives Cursor's AI the ability to read, write, and search files with more control than the built-in file access.

Option A: Using npx (Node-based servers)

Most MCP servers can be run directly with npx, which downloads and executes the package without a global install:

// .cursor/mcp.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/directory"
      ]
    }
  }
}

Option B: Using Python-based servers

Python MCP servers — including those distributed through AgentNode — are typically run with python or uvx:

// .cursor/mcp.json
{
  "mcpServers": {
    "web-scraper": {
      "command": "python",
      "args": ["-m", "agentnode_mcp", "--tool", "web-scraper"],
      "env": {
        "AGENTNODE_API_KEY": "your-key"
      }
    }
  }
}

Option C: Installing from AgentNode

AgentNode hosts verified MCP servers that have been through the trust verification pipeline. To find MCP-compatible tools, find MCP servers on AgentNode and filter by "MCP" compatibility. Each package page includes the exact configuration snippet for Cursor.

Step 3: Configuring Multiple Servers

Most developers run several MCP servers simultaneously. Here is a realistic configuration for a full-stack developer:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./src"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://dev:password@localhost:5432/myapp"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    },
    "web-search": {
      "command": "python",
      "args": ["-m", "agentnode_mcp", "--tool", "web-search"],
      "env": {
        "AGENTNODE_API_KEY": "your-key"
      }
    }
  }
}

With this setup, Cursor's AI can read your source files, query your database, interact with GitHub issues and PRs, and search the web — all from within the agent panel.

Step 4: Verifying the Connection

After creating your configuration file, verify that Cursor recognizes your MCP servers:

1. Restart Cursor — MCP configuration is read at startup. After creating or editing mcp.json, restart the IDE.
2. Open the agent panel — press Cmd+I (Mac) or Ctrl+I (Windows/Linux)
3. Check the tools indicator — at the bottom of the agent panel, you should see a tools icon with a number indicating how many MCP tools are available
4. Click the tools icon — this opens a panel showing all connected MCP servers and their available tools
5. Test with a prompt — ask the agent something that requires a tool, e.g., "List all files in the src directory" (if you configured the filesystem server)

If the tools icon shows zero or the server shows as disconnected, jump to the troubleshooting section below.

Best MCP Servers for Coding Workflows

Based on what developers actually use day-to-day, here are the most valuable MCP servers for coding workflows:

Essential: Filesystem Server

Gives the AI granular file operations — reading specific line ranges, searching across files, creating directories. More capable than Cursor's built-in file access for complex operations.

Essential: Database Server

PostgreSQL, MySQL, and SQLite servers let the AI query your development database directly. Invaluable for debugging data issues, writing migrations, and understanding schema relationships.

High Value: GitHub Server

Read issues, create PRs, check CI status, and review diffs — all from the agent panel. Particularly useful for triaging issues and writing PR descriptions.

High Value: Web Search

When the AI needs to look up documentation, check for known issues, or research an error message, a web search MCP server provides answers without you leaving the editor.

Specialized: Docker Server

Manage containers, read logs, and inspect running services. Useful for developers working with containerized development environments.

For a curated list of the most trusted options, see our guide to the best verified MCP servers for 2026. All servers listed there have been through AgentNode's verification pipeline and carry trust scores.

Cursor MCP vs. Claude Desktop MCP

If you have used MCP with Claude Desktop, you will notice some differences in the Cursor implementation:

Feature	Cursor	Claude Desktop
Config location	.cursor/mcp.json	~/Library/Application Support/Claude/claude_desktop_config.json
Config format	Same JSON structure	Same JSON structure
Server types	stdio only	stdio and SSE
Tool approval	Per-session or auto-approve	Per-call approval
Project scoping	Per-project or global	Global only
Agent mode	Required (Cmd+I)	Always available in chat

The good news is that the server configuration format is nearly identical. If you have an MCP server working in Claude Desktop, you can usually copy the configuration directly into your Cursor mcp.json with minimal changes. For a complete walkthrough covering both clients, see the tutorial on MCP servers for Claude and Cursor.

Troubleshooting Common Issues

Server Shows as "Disconnected"

This usually means the server process failed to start. Common causes:

• Wrong command path — ensure npx or python is in your system PATH. Try running the command manually in a terminal first.
• Missing dependencies — the server package might require additional installations. Check the server's documentation.
• Port conflict — if the server uses a network port, another process might be using it. Most stdio-based servers avoid this issue.

Tools Not Appearing

If the server connects but no tools show up:

• Check the server version — older MCP server versions may not support the tool listing protocol correctly
• Restart Cursor — tool discovery happens at connection time, not dynamically
• Check logs — open Cursor's developer tools (Help > Toggle Developer Tools) and look for MCP-related errors in the console

Environment Variables Not Working

Cursor passes environment variables from the env section to the server process, but:

• Do not use shell expansion — $HOME or ~ in env values will not be expanded. Use absolute paths.
• Sensitive values — avoid committing API keys in project-level mcp.json. Use the global config for secrets, or use a .env file with a reference.
• Restart required — env changes are read at server startup, so restart Cursor after editing.

Server Crashes During Use

If a server works initially but crashes when the AI calls a tool:

• Check memory — some MCP servers consume significant memory, especially those processing large files
• Check timeouts — long-running tool calls may exceed Cursor's default timeout. Some servers have configurable timeouts in their args.
• Update the server — crashes are often bugs in specific server versions. Update to the latest version.

Permission Errors

Filesystem and database servers often run into permission issues:

• Filesystem — the server runs with the same permissions as Cursor. Ensure Cursor has access to the directories you configure.
• Database — use a read-only database user for safety. Write operations through an MCP server should require explicit confirmation.

Security Considerations

MCP servers have access to your local machine, your credentials, and your data. Before installing any MCP server:

1. Check the source — review the server's repository. Is it maintained? Are there recent commits?
2. Check the trust score — if the server is on AgentNode, look for a Verified or Gold tier rating
3. Use read-only credentials — for database servers, use a read-only user. For API servers, use tokens with minimal scopes.
4. Limit filesystem access — configure filesystem servers with the narrowest directory scope possible
5. Review permissions — understand what network access and filesystem access the server needs before granting it

For a comprehensive security checklist, see the AgentNode setup documentation which covers safe MCP server deployment in detail.

Advanced: Running Custom MCP Servers

If the available MCP servers do not cover your use case, you can build your own. The basic pattern is:

# my_mcp_server.py
from mcp.server import Server
from mcp.types import Tool, TextContent

server = Server("my-custom-tools")

@server.tool("check_api_health")
async def check_api_health(url: str) -> list[TextContent]:
    """Check if an API endpoint is responding."""
    import httpx
    async with httpx.AsyncClient() as client:
        response = await client.get(url, timeout=10)
        return [TextContent(
            type="text",
            text=f"Status: {response.status_code}, Time: {response.elapsed.total_seconds():.2f}s"
        )]

if __name__ == "__main__":
    import asyncio
    asyncio.run(server.run())

Then configure it in Cursor:

{
  "mcpServers": {
    "custom-tools": {
      "command": "python",
      "args": ["./scripts/my_mcp_server.py"]
    }
  }
}

Once your custom server is working, consider publishing it as an ANP package on AgentNode so other developers can benefit. The verification pipeline will test it automatically and assign a trust score.

What's Next

MCP support in Cursor is evolving rapidly. Upcoming features on the Cursor roadmap include SSE transport support (enabling remote MCP servers), improved tool approval workflows, and better error reporting for failed tool calls.

In the meantime, the combination of Cursor's AI assistant and well-chosen MCP servers creates a development environment that is significantly more capable than either component alone. Start with one or two essential servers, verify they work, and expand from there.