Add your first MCP server to Cursor

Out of the box, Cursor's AI can read your code and not much else. MCP servers give it more abilities: look up up-to-date library docs, read your issue tracker, open a browser, query a database.

MCP stands for Model Context Protocol. It's a standard way of plugging tools into AI apps, a bit like USB for AI. A tool that speaks MCP is called an MCP server, and apps like Cursor that connect to it are clients. Because it's a standard, the same server works in Cursor, Claude Code and other clients.

This recipe adds two servers to Cursor: one that runs on your computer, and one that's hosted online.

Before you start

Cursor installed, with a project open. Cursor has a free plan with limited requests, so you can follow along without paying. Check cursor.com/pricing for current plans.
Node.js installed (for the local example). Local servers like this one start with a tool called npx, which comes with Node.js. Test it by opening a terminal and typing node --version. If you see a version number you're fine. If not, install Node.js from nodejs.org.

How Cursor finds MCP servers

Cursor reads a file called mcp.json. There are two places for it:

File	Applies to
`.cursor/mcp.json` in your project folder	Just this project
`~/.cursor/mcp.json` in your home folder	Every project

(The leading dot in .cursor makes it a hidden folder. Cursor's file explorer will still show it once it exists.)

The file always has the same outline: a top-level mcpServers object, with one entry per server.

Recipe 1: a local server (Context7)

Context7 fetches current documentation for libraries and frameworks. It's a great first server because it's useful straight away: AI models often quote out-of-date APIs, and this fixes that.

Step 1: create the config file

In your project, create a folder named .cursor, then a file inside it called mcp.json:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

What it says, in plain English:

"context7" is the nickname you're giving the server.
"command": "npx" means "run this using npx".
"args" are the extra words that follow: -y (say yes to prompts) and the name of the package to run.

Step 2: check that Cursor sees it

Open Cursor's settings and find the MCP section (you can search for "MCP" in settings). You should see context7 in the list, with a toggle to turn it on or off. If it shows a green indicator or a list of tools, it's running. If it shows an error, jump to the troubleshooting section below.

If Cursor doesn't pick up the file straight away, fully quit and reopen it.

Step 3: use it

Start a chat with Cursor's AI and ask for something that needs current docs:

Using Context7, show me how to set up routing in the latest version of Astro.

The AI will ask permission to use the server's tools. Context7 exposes two: resolve-library-id (find the right library) and query-docs (fetch the relevant docs). Approve and you'll see them being called.

Recipe 2: a remote server (Linear)

Some servers are hosted by the company, so there's nothing to install. You just give Cursor a web address. Linear's server is an example (you'll need a Linear account to use it).

Add it alongside the first one:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "linear": {
      "url": "https://mcp.linear.app/mcp"
    }
  }
}

The difference: local servers use command and args; remote servers use url. When a remote server needs a key, you can add a headers section for it, and the docs also describe an auth option for OAuth-style setups.

Linear signs in through OAuth, so once you enable it, Cursor sends you to your browser to approve access. Linear's docs also give a read-only address, https://mcp.linear.app/mcp/readonly, if you'd prefer the AI to look but not change anything.

Keeping secrets out of the file

Some servers need a key or token. Don't paste secrets into a file you might commit to Git. Cursor lets you reference environment variables inside command, args, env, url and headers using the ${env:NAME} form:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "some-mcp-package"],
      "env": { "API_KEY": "${env:MY_API_KEY}" }
    }
  }
}

Set MY_API_KEY in your computer's environment, and the file itself holds no secret. If you must use a real key in a file, keep it in the global ~/.cursor/mcp.json, not the project one.

Staying safe with MCP

MCP servers can do real things, so treat them like apps you install:

Only install servers you trust. Prefer official ones from the company or the Model Context Protocol project.
Use read-only when you can. If a server has a read-only mode, use it until you need more.
Give minimal access. Create tokens with the fewest permissions that work.
Read the approval prompts. Cursor asks before the AI uses a tool. Take a second to read what it's asking.
Be cautious with databases. Point them at a development copy, not your live data.

Cursor also has an MCP allowlist feature to restrict which commands and URLs may run, which is useful for teams.

Troubleshooting

The server doesn't appear in settings. Check the file is at .cursor/mcp.json (with the leading dot), then quit and reopen Cursor.

JSON errors. JSON is picky. Every "name" needs quotes, items are separated by commas, and the last item in a list has no trailing comma. Paste your file into a JSON validator if you're stuck.

"npx: command not found" or the server won't start. Node.js isn't installed or isn't on your path. Run node --version in a terminal to check. Install Node.js, then restart Cursor.

It works in the terminal but not in Cursor. Cursor may not see the same environment as your terminal. Try launching Cursor from your terminal, or use full paths in command.

The AI doesn't use the tool. Mention it by name in your request ("use Context7 to…"). Also check the server's toggle is on.

Try more servers

Once the pattern clicks, adding more is the same recipe: copy a config snippet, paste it into mcpServers, restart. Our MCP directory has paste-ready configs for:

Filesystem, for controlled access to folders on your computer
Fetch, to read web pages as Markdown
Playwright, to drive a real browser
GitHub, to work with repos and pull requests

Prefer the terminal? The same servers work in Claude Code, and our guide to connecting Claude Code to MCP servers shows how.

Recap

Make .cursor/mcp.json (project) or ~/.cursor/mcp.json (global).
Add a server under mcpServers: command + args for local, url for remote.
Check Cursor's MCP settings for a running server.
Ask the AI to use it, and approve the tool calls.