Plug In an MCP Server in Cursor:Your First Working Connection

You know MCP is a standard plug for tools and data. This page makes that plug real in Cursor: write mcp.json, connect a known server, and run one approved tool call. You do not write a server yet.

Before you start

• Terms like host, server, tool, and stdio are defined in MCP Without the Hype.
• You need Node.js on your PATH so npx works (node -v in a terminal).
• Use Agent chat in Cursor (not only Ask) so tool calls can run with approval.

Where config lives

Cursor reads MCP servers from JSON files:

Location	Scope
.cursor/mcp.json	This project only
~/.cursor/mcp.json	Your user account, every project

Both files are merged. If the same server name appears in both, the project file wins.

For this lab, use a project file so the experiment stays in one folder. Official reference: Cursor MCP docs.

Note: Never commit API keys or tokens in mcp.json. Use ${env:NAME} (shown below) or keep secrets only in the global file that stays off git.

Field-by-field: local stdio

A local server is a process Cursor starts. Typical fields:

Field	Required	Meaning
type	Yes (for stdio)	"stdio" — local command transport
command	Yes	Executable on your PATH (npx, node, …)
args	No	Arguments passed to that command
env	No	Environment variables for the server process
envFile	No	Path to a .env file (stdio only)

Cursor expands variables in command, args, env, url, and headers:

Variable	Expands to
${userHome}	Your home directory
${workspaceFolder}	Project root (folder that contains .cursor/mcp.json)
${env:NAME}	Value of environment variable NAME
${workspaceFolderBasename}	Name of the project root folder
${pathSeparator} / ${/}	OS path separator

Even when today’s lab needs no secret, get used to this pattern for later servers:

{
  "mcpServers": {
    "example-with-secret": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "env": {
        "API_KEY": "${env:MY_SERVICE_API_KEY}"
      }
    }
  }
}

Set MY_SERVICE_API_KEY in your shell profile or OS environment — not in the committed JSON.

Remote shape (recognize only)

Cursor also supports remote servers with a URL (Streamable HTTP or SSE). A minimal sketch:

{
  "mcpServers": {
    "remote-example": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_REMOTE_TOKEN}"
      }
    }
  }
}

Do not start here. Connect locally with stdio first. Hosting a public URL is a later post in the series. SSE is supported by Cursor; this lab does not teach it.

Lab: filesystem server on a throwaway folder

Start from a blank slate. You will create two folders with different jobs: one you open in Cursor, and one the MCP server may read. That split is the point — MCP grants access to a folder outside the project you opened.

Path	Role	Open in Cursor?
~/mcp-cursor-lab	New Cursor project (workspace). Put .cursor/mcp.json here.	Yes — File → Open Folder
~/mcp-lab	Sandbox data allowlisted by the filesystem server	No — MCP-only access

Use the official filesystem package: @modelcontextprotocol/server-filesystem. No API keys. Each step below states what you are doing, why, what will change, and what success looks like.

1. Create a sandbox the server may read

• What: Create ~/mcp-lab and write hello.txt. This is not a Cursor project — do not open it as a workspace.
• Why: The filesystem server needs an allowlisted folder. A throwaway path keeps the experiment off your home directory and off any real repo.
• What changes: A new directory and one file on disk. Nothing in Cursor yet.
• Expect: cat ~/mcp-lab/hello.txt prints hello from MCP lab. No server appears in Cursor yet — that is step 2.

In a terminal:

mkdir -p ~/mcp-lab
echo 'hello from MCP lab' > ~/mcp-lab/hello.txt

2. Create a Cursor project and register the server

• What: Create an empty project at ~/mcp-cursor-lab, open that folder in Cursor, and add .cursor/mcp.json so lab-fs points at ~/mcp-lab.
• Why: Cursor only starts MCP servers listed in a workspace config. A project file keeps this experiment in one folder (~/.cursor/mcp.json would attach it to every repo).
• What changes: New folder ~/mcp-cursor-lab plus .cursor/mcp.json inside it. Sandbox files from step 1 are unchanged. The last args path (${userHome}/mcp-lab) is the only link between the two folders.
• Expect: Explorer shows ~/mcp-cursor-lab (empty except .cursor/). mcp.json is valid JSON. The server may still be missing or disconnected until you reload — that is step 3.

In a terminal:

mkdir -p ~/mcp-cursor-lab

In Cursor: File → Open Folder → choose ~/mcp-cursor-lab.

Then create .cursor/mcp.json at the root of that project:

{
  "mcpServers": {
    "lab-fs": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${userHome}/mcp-lab"
      ]
    }
  }
}

The last argument is the allowlisted directory. The server must not reach outside that path.

Windows note: if npx fails to start under Cursor, wrap it with cmd / /c as shown in the filesystem server docs — same idea, different launcher.

3. Reload and confirm Connected

• What: With ~/mcp-cursor-lab still open, restart Cursor (or reload the window), then open the MCP settings page and confirm lab-fs.
• Why: Cursor reads mcp.json when MCP starts, not the instant you save the file. The status page is where you verify the process actually connected.
• What changes: Cursor starts the lab-fs process for this project. Files in ~/mcp-lab are unchanged.
• Expect: Server lab-fs listed, status Connected (green / healthy), filesystem tools visible (list directory, read file, and similar). If red or missing, go to Troubleshooting.

After saving mcp.json, restart Cursor or reload the window (Developer: Reload Window from the Command Palette) so MCP picks up the file.

Then open the MCP settings page — do not hunt menus by eye. Use the Command Palette:

1. Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS). That is the Command Palette (Ctrl+P alone is Quick Open for files — different tool).
2. Type MCP until you see a command like View: Open MCP Settings (wording can vary slightly by Cursor version).
3. Run it. You should land on the MCP / Tools panel.

Alternate path: Ctrl+, (or Cmd+,) opens Cursor Settings → look for Tools & MCP or Tools & Integrations → MCP. Sidebar Customize → MCPs also exists in some builds, but it is easy to miss — prefer the Command Palette.

On that page, find lab-fs, confirm it is toggled on, and use any refresh/reload control next to the server list if the entry looks stale.

4. Call one tool from Agent chat

• What: In a new Agent chat (still in ~/mcp-cursor-lab), ask to list ~/mcp-lab and read hello.txt via lab-fs tools. Approve the call after checking the path.
• Why: Connected only means the process started. One approved tool call proves MCP can reach the sandbox outside the project you opened.
• What changes: One read of ~/mcp-lab. Files under ~/mcp-cursor-lab are not the target.
• Expect: A listing that includes hello.txt, and contents hello from MCP lab.

Open a new Agent chat. Ask something that needs the sandbox — not the empty project root:

Using the lab-fs MCP tools, list the files in my MCP lab folder and read hello.txt.

When Cursor asks for approval, expand the tool call, check the path arguments, then approve.

That is the whole beginner loop: config → Connected → one approved tool call.

Marketplace and one-click install

Cursor’s Marketplace (and, in some builds, Customize → MCPs) can install some servers with one click (including OAuth for hosted products). Open that UI the same way as step 3: Command Palette → type MCP. This post teaches mcp.json because the same shape transfers to other hosts and to servers you build yourself later.

Other hosts

The same stdio server works in Claude Desktop and similar MCP hosts; only the config file path changes. This is not a second full tutorial — one mental model, many config locations.

Troubleshooting

Symptom	What to check
Server never appears	Path must be .cursor/mcp.json (not .cursor/mcp/config.json). Validate JSON (trailing commas break the file).
Red / disconnected	Run the same npx -y @modelcontextprotocol/server-filesystem … command in a terminal. Fix Node/npx first.
“Works in global, not project”	Same server name in both files → project wins. Rename one entry or edit the file you think you are editing.
Tools never offered	Reload after config changes; start a new Agent chat; open MCP settings via Command Palette (Ctrl/Cmd+Shift+P → MCP) and confirm lab-fs is toggled on.
Need logs	Output panel → MCP Logs (Cursor FAQ on debugging MCP).

When you build your own server later, the MCP Inspector is a strong debug path before Cursor wiring — that lab belongs with writing the server, not here.

Wrap-up

You pointed Cursor at a local MCP server with mcp.json, confirmed Connected, and ran one approved tool against a bounded folder. Series hub and glossary: MCP Without the Hype.

Next optional step Build your own tools-only server over stdio. Build Your First MCP Server in TypeScript →