How to Use MCP in Cursor: The Missing Manual (2026 Guide)

You paste the ticket. Then you paste the code. Then you ask for a fix. But then you realize you forgot the database schema, so you copy that too. By the time you have the context ready, you could have just written the SQL query yourself.

This is the "Context Wall" that every developer hits. We want "magic" workflows where the AI just knows the state of the repo and the ticket requirements, but we are stuck acting as manual data pipelines for our own tools.

The Model Context Protocol (MCP) fixes this. It stops your LLM from being a passive chatbot that reads text and turns it into an active agent that can query databases, search documentation, and execute commands.

But most tutorials stop at "Hello World" weather apps. That doesn't help you ship code. This guide covers how to build a production-grade MCP stack using Linear, Postgres, and GitHub, so you can stop copy-pasting and start engineering.

Key Takeaways

• From chatbot to agent: MCP gives Cursor the ability to execute tools and query live data, not just process static text.
• Security first: Never hardcode API keys in your mcp.json file because local storage effectively exposes them.
• The "pro stack": Skip the toy examples and focus on connecting high-leverage tools like Linear, Postgres, and GitHub.
• Scaling caution: Connecting too many tools causes "Token Bloat," which degrades model performance and increases cost.
• Governance matters: Connecting a tool isn't enough. You must use .cursorrules to instruct the agent when and how to use it.

What is MCP in Cursor? (And Why You Need It)

The Model Context Protocol (MCP) is an open standard that connects AI models to data sources. Think of it as a USB-C port for LLMs. Before MCP, you had to manually paste context into the chat window. With MCP, the model can "reach out" and grab the data it needs, when it needs it.

In Cursor, this architecture is split into three parts:

1. The Host (Cursor): The interface where you chat.
2. The Client: The underlying engine that decides when to call a tool.
3. The Server: The bridge to your actual tool (like a Postgres database or Linear API).

When you ask Cursor to "find the bug in the latest ticket," it doesn't just guess. It uses the MCP protocol to query Linear for the ticket details, then uses a filesystem MCP to read your code, and finally synthesizes an answer.

Prerequisites & Core Concepts

Before we write any configuration, you need to understand the transport layer. Choosing the wrong one is the most common reason for connection failures and high latency.

There are two primary ways to connect an MCP server to Cursor: Stdio and SSE.

Stdio (Standard Input/Output) is the default for local development. It runs the MCP server as a subprocess directly within Cursor. It is fast because there is no network overhead, but it can be harder to debug since logs often get swallowed by the IDE.

SSE (Server-Sent Events) is designed for remote connections. If you want to share an MCP server with your team or host it in a Docker container, you use SSE.

Experienced engineers often start with Stdio for speed but migrate to SSE when they need to inspect traffic or share tools across the team.

You also need to distinguish between Tools and Resources.

• Resources are read-only data sources (like reading a log file or fetching a documentation page).
• Tools are executable actions (like creating a Linear ticket or running a SQL query).

Step 1: Configure mcp.json (The "Hello World")

To connect a server, you need to edit the mcp.json configuration file. You can access this in Cursor by navigating to Cursor Settings > Features > MCP.

Instead of a weather app, we will configure a Filesystem Server. This is a practical "Hello World" that allows Cursor to search and read files outside of your immediate open workspace, which is critical for monorepos.

Here is the exact syntax you need. Note the structure of command and args.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/desktop/allowed-path",
        "/Users/username/downloads/allowed-path"
      ]
    }
  }
}

Critical Warning: JSON is unforgiving. A single trailing comma after the last closing brace will break the entire configuration. If your servers don't appear, check your syntax first.

Also, be careful with the env block. While you can add API keys directly here, local files are not secure storage. We will discuss secure alternatives in the scaling section, but for now, ensure your mcp.json is included in your .gitignore to prevent accidental commits.

Step 2: The "Essential Developer Stack" (Real-World Examples)

Most tutorials stop after connecting a weather API. That's a "Toy" use case.

But you aren't building a weather app. You're building software.

To make Cursor a true "Daily Driver," you need to connect the tools that govern your actual workflow: Linear (Issues), Postgres (Data), and GitHub (Code). These tools aren't just for chat; they work seamlessly within Cursor's Composer mode to edit multiple files based on live ticket data.

Here is the difference between a toy setup and a pro stack:

1. Postgres: Query Live Data Safely

Connect a Read-Only Postgres user to your development database. This allows the agent to inspect the schema and verify data integrity before writing migration scripts.

Configuration:

{
  "postgres": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-postgres",
      "postgresql://user:password@localhost:5432/dbname"
    ]
  }
}

2. Linear: Manage Tickets from Chat

Instead of alt-tabbing to check acceptance criteria, let the agent fetch the ticket directly. Use the official Linear MCP server to read issues and post comments.

Configuration:

{
  "linear": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-linear"
    ],
    "env": {
      "LINEAR_API_KEY": "lin_api_key_here"
    }
  }
}

3. GitHub: Context Beyond Local Files

Your local checkout only has the current state of the code. The GitHub MCP server gives the agent access to history, PR discussions, and issues across the entire organization.

Configuration:

{
  "github": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-github"
    ],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_token_here"
    }
  }
}

Step 3: Verify & Debug Your Connection

After saving mcp.json, restart Cursor to reload the configuration. Then navigate to Cursor Settings > Features > MCP.

You should see a list of your servers with a green indicator light next to each one.

If a server is red or missing, check these common issues:

1. "Stdio connection error": Usually means the command (npx, uv) isn't in your system path. Use absolute paths to the executable.
2. "Environment variable missing": Double-check that your API key is correctly named in the env block.
3. "Command not found": Ensure you have Node.js or Python installed and accessible to Cursor.

For advanced debugging, you can use the MCP Inspector tool to view the raw JSON-RPC messages being sent between Cursor and the server. This is invaluable when building custom tools.

Pro Tip: Governance with Cursor Rules

Connecting a tool is only half the battle. Experienced users quickly discover a frustrating problem: "Context Amnesia."

You ask the agent to fix a bug, and it hallucinates a solution instead of checking the database schema you just connected. Or worse, it forgets to check the ticket requirements in Linear.

To fix this, you need Governance. You must explicitly instruct the agent when and how to use the tools. The best way to do this is with a .cursorrules file in your project root.

This simple file acts as a "System Prompt" that persists across sessions, ensuring the agent always respects your workflow rules.

Scaling Your Agent: From Local JSON to Enterprise Gateway

As you add more tools like Jira, Slack, Salesforce, and internal APIs, you will hit the "Token Bloat Trap."

Every tool you add injects a schema description into the context window. If you have 20 tools, you might waste 10,000 tokens just describing what the tools do before you even ask a question. This makes the model slower, dumber, and more expensive.

Plus, managing API keys in a local mcp.json file is a security nightmare for teams. You can't commit that file to git, so every engineer has to manually copy-paste keys.

This is why serious engineering teams move from local configuration to an MCP Gateway.

Apigene provides the mission-critical runtime infrastructure for the agentic era. Instead of connecting Cursor directly to 50 different APIs, you connect it to a single Apigene Gateway.

The Gateway handles the authentication, logging, and routing. It only exposes the relevant tools to the model based on the user's intent, solving the token bloat problem. It also provides a secure vault for your API keys, so you never have to worry about a junior engineer accidentally committing a production secret.

Conclusion: Build, Don't Just Chat

We are moving past the era of "Chat with your Code." We are entering the era of "Agentic Workflows."

MCP allows you to turn Cursor into a true development partner—one that can read the ticket, check the database, and write the code that passes the tests.

Start small. Configure the Linear and Postgres MCP servers today. Add a .cursorrules file to govern them. And when your team is ready to scale, look at a gateway solution to manage the complexity.

The tools are ready. The protocol is standard. Now it's time to build.

FAQs

How to use MCP in Cursor chat?

Once configured in mcp.json, MCP tools are automatically available to the agent. You can invoke them naturally by asking questions like "Check the latest Linear ticket" or "Query the users table." The agent will decide when to call the tool based on your prompt and the tool's description.

How to use Docker MCP with Cursor?

To use Docker, configure your mcp.json to run a docker run command instead of npx. Ensure you map the necessary volumes and ports. This is an excellent way to isolate the tool's environment and dependencies from your local machine.

How to enable chat MCP enabled?

MCP support is enabled by default in recent versions of Cursor. If you don't see it, go to Settings > Features and ensure the "MCP" toggle is active. You may need to restart the IDE after changing this setting.

Where is the mcp.json file located?

You can open it directly from the Cursor UI: Settings > Features > MCP > Open Configuration File. On disk, it is typically located in your user's AppData/Roaming/Cursor (Windows) or ~/Library/Application Support/Cursor (macOS) directory.

Is it safe to use API keys in MCP?

Storing API keys in plain text in mcp.json is not recommended for production credentials. Use environment variables or a secure gateway like Apigene to manage secrets. If you must use local keys, ensure mcp.json is in your global .gitignore.

Why is my MCP server not showing up?

The most common cause is a syntax error in your mcp.json file (usually a trailing comma). Check the "Output" tab in Cursor and select "MCP" from the dropdown to see error logs. Also, verify that the command (e.g., npx, python) is in your system PATH.