How to Use MCP with Cursor Editor

Cursor’s MCP support lets you connect external tools — databases, APIs, file systems, web search, internal services — directly to the AI inside your IDE. Once connected, Cursor’s AI can query your database while reviewing code, search internal documentation while writing a feature, or read a GitHub issue while implementing a fix — all without switching context. This guide covers how to set up MCP servers in Cursor, which servers are most useful for coding workflows, and how to get the most out of the integration.

How MCP Works in Cursor

Cursor implements the Model Context Protocol as a client — it connects to MCP servers you configure and makes their tools available to the AI in chat and Composer sessions. When you ask Cursor a question or give it a task, the AI can call any of the connected tools as part of forming its response. The tool calls are visible in the conversation: you see when Cursor queries a database, searches the web, or reads a file through an MCP server, and the results of those calls appear inline before the AI’s final response.

This transparency is important. Unlike hidden tool use in some AI systems, Cursor shows you exactly which MCP tools were called and what they returned, so you can verify that the AI’s answer is based on accurate data and understand where its information came from.

Configuring MCP Servers in Cursor

MCP server configuration in Cursor lives in a mcp.json file. There are two scopes:

• Global config at ~/.cursor/mcp.json — servers available in all Cursor projects on your machine
• Project config at .cursor/mcp.json in the project root — servers available only in that project, committed to the repository so the whole team gets them

The format follows the same structure as Claude Desktop’s MCP config: each server entry specifies a name, the command to launch it, its arguments, and any environment variables it needs. Cursor picks up config changes automatically — no restart required in most cases, though some servers need a reload to initialise properly.

To verify a server is connected, open Cursor Settings → MCP. Connected servers appear with a green indicator; servers that failed to start show an error you can expand for diagnostics. This settings panel is the first place to check when a server is not behaving as expected.

The Most Useful MCP Servers for Cursor

Not all MCP servers are equally valuable in an IDE context. The ones that make the biggest difference to a coding workflow are:

GitHub MCP: lets Cursor read issues, pull requests, and comments directly. When you start a Composer session with “implement the feature described in issue #142,” Cursor fetches the issue, reads the full description and any attached comments, and uses that as context for the implementation. This eliminates the context switch of opening a browser tab to read the issue before returning to the IDE.

Database MCP: invaluable when writing queries or data-layer code. Rather than keeping a separate database client open to check table structures, Cursor can inspect the schema directly while writing repository code. “Write a query that finds all users who made a purchase in the last 30 days but haven’t logged in since” — Cursor checks the actual column names and relationships before generating SQL rather than guessing from the ORM model names.

Web search MCP: essential for keeping up with fast-moving libraries. When writing code that uses a library version released after the model’s training cutoff, Cursor can search for the current API and write code that actually works rather than relying on outdated training data. Particularly valuable for AI/ML libraries where APIs change significantly between versions.

Filesystem MCP: useful when the project you are working in references files outside its own directory — shared config files, documentation in a separate repo, templates in a central location. The filesystem server lets Cursor read those files as context without requiring you to copy their contents into the chat.

GitHub MCP Setup and Use

The GitHub MCP server (@modelcontextprotocol/server-github) requires a GitHub personal access token with repo scope. Add the server to your Cursor MCP config with the token as an environment variable. Once connected, Cursor can list repositories, read issues and PRs, search code across your GitHub organisations, and create or update issues.

For Composer workflows, the GitHub integration changes how you start sessions. Instead of describing a feature from memory, reference the issue directly: “implement issue #234 from the mljourney/backend repo.” Composer fetches the issue, reads the acceptance criteria and any design discussion in the comments, and uses that as the ground truth for the implementation. This produces implementations that are more aligned with what was agreed in the issue rather than your mental summary of it — a meaningful quality improvement for any task where the issue discussion contains important detail.

Project-Level vs Global MCP Configuration

The choice between project-level and global MCP config has practical implications for team workflows. Global config (in ~/.cursor/mcp.json) is right for personal servers that you always want available — your personal web search API key, access to your own databases, filesystem access to your local projects folder. Project config (in .cursor/mcp.json, committed to the repo) is right for servers that every team member working on that project should have access to — the project’s development database, the GitHub repo connection, any internal documentation server. Committing project MCP config to the repository means a new team member gets the full set of IDE integrations immediately after cloning, with only their personal credentials to supply.

Debugging MCP Issues in Cursor

When an MCP server is not working as expected in Cursor, a systematic debugging approach saves time. First, check Settings → MCP to see if the server shows a connection error — the error message usually points directly at the problem (wrong path, missing environment variable, Node.js version mismatch). Second, test the server independently outside Cursor by running the server command directly in a terminal with the same environment variables — if it fails there, the problem is in the server configuration rather than Cursor’s integration. Third, check the Cursor developer console (Help → Toggle Developer Tools) for MCP-related error messages that do not appear in the settings UI. Most MCP issues in Cursor fall into three categories: the server binary is not found (Node.js not in PATH, package not installed), the environment variables are not being passed correctly, or the server itself has a bug that only manifests with certain tool calls.

Writing Your Own MCP Server for Cursor

For teams with internal tools that do not have existing MCP servers — proprietary APIs, internal knowledge bases, custom deployment systems — writing a minimal MCP server is more accessible than it sounds. The MCP SDK for TypeScript and Python provides scaffolding that handles the protocol mechanics; you only need to implement the tool definitions (name, description, input schema) and the handler functions that execute each tool. A simple server that exposes two or three tools for a specific internal API can be built in a few hours and makes that API accessible to Cursor’s AI in exactly the same way as any official server. For teams where developers regularly look things up in internal systems while coding, a custom MCP server that bridges those systems into Cursor can save meaningful time across the team.

MCP support in Cursor transforms the IDE from a tool that understands your codebase to a tool that understands your codebase and your broader development context — the issues you are working from, the database your code runs against, the documentation your team maintains, the APIs your code calls. Each connected server adds a dimension of context that makes Cursor’s AI assistance more accurate, more relevant, and less dependent on you manually supplying context that already exists in your development environment.

MCP and Cursor Rules Files Working Together

MCP servers and Cursor’s rules file are complementary — rules files set persistent context about how the AI should behave in a project, while MCP servers provide live access to data and tools. Combining them produces a particularly coherent experience. A rules file that specifies “when writing database queries, always check the actual schema via the database MCP server before generating SQL” tells Cursor to use the tool proactively rather than only when you explicitly ask. Similarly, a rule like “when implementing a feature, read the linked GitHub issue before writing code” turns the GitHub MCP server from a tool you manually invoke into a consistent part of every Composer session. These rules-plus-MCP combinations effectively encode your development workflow into the AI’s default behaviour, reducing the overhead of directing each session manually.

Keeping MCP Config in Sync Across Team Members

For teams where multiple developers use Cursor with shared MCP servers, keeping configurations in sync is an ongoing maintenance task. The project-level .cursor/mcp.json committed to the repository handles the server definitions, but API keys and credentials are per-developer and should never be committed. The cleanest pattern: define all servers in the project config using environment variable references for credentials, and document in the project README which environment variables each developer needs to set. A .env.example file listing the required variables with placeholder values makes onboarding straightforward. This approach means new team members clone the repo, set their personal credentials as environment variables, and immediately have the same MCP-connected Cursor setup as everyone else — no tribal knowledge required about which servers the team uses or how to configure them.