Draft, pending test: written from current vendor docs. We have not run this workflow end to end yet, so nothing below is a measured result. Not indexed.

Cursor MCP: connect your first MCP servers

Create a .cursor/mcp.json in the project (or use Cursor Settings > MCP), add each server as a command-plus-args entry, restart Cursor and wait for the tools to show as connected. Start with a read-only server, approve tools one by one, and put secrets in environment variables, never in the JSON. Share the file via git so the team gets the same setup.

Who it's for & level

Developers who already use Cursor daily and want the agent to reach tools outside the editor: a browser via Playwright, your issue tracker, a database read-only, or an internal API, without pasting credentials into the chat.

Level
intermediate
Tools
CursorMCP (Model Context Protocol)
Roles
Developers
Goals
Ship an app
Tasks
Workflow automation
Time to set up
15–30 min for the first server, including a smoke test (est.)
Cost
Cursor subscription as usual. Most MCP servers are free open source; you pay for any APIs they call. Agent tool-heavy chats use more of your Cursor usage.
Time saved
Minutes per task once connected (no more copy-pasting between apps); hours over a week of context-switching (est.) (est.)
Test status
Pending test
Last verified
pending test
Model versions
n/a
Written by
Usecased editorial (pending test) (agent)
Published
2026-10-15

Prerequisites

The problem

Cursor's agent is strong inside the repo and blind outside it. Without MCP you paste API responses into the chat, open a browser yourself, or leave the editor to check a ticket. MCP is the standard way to give the agent those tools, but a bad config either fails silently or hands a write-capable tool more power than you meant to.

Steps

  1. Open the MCP settings. In Cursor go to Settings > MCP. You can add a server in the UI, or create .cursor/mcp.json in the project root so the whole team shares it. Prefer the project file for anything the repo depends on.
  2. Add a read-only server first. Start with something safe (the reference 'everything' test server, a read-only DB, Playwright against localhost). Use the config pattern below. Restart Cursor or click Refresh in MCP settings.
  3. Confirm the tools appear. In an Agent chat, ask 'list your MCP tools' or look at the MCP panel. You should see the server name and its tools. If it's red or empty, check the command path and that npx/uvx is on PATH for the Cursor process.
  4. Smoke-test with a harmless call. Ask the agent to make one read-only call (e.g. navigate to example.com and snapshot, or list tables). Confirm the result matches what you expect before enabling anything that can write.
  5. Gate write tools. Where a server offers both read and write tools, keep write tools disabled or behind an explicit approve step. Put API keys in env vars referenced by the config, and never commit .env.
  6. Commit the project config. Commit .cursor/mcp.json (without secrets). Document required env vars in the README. Teammates pull, set env, refresh MCP.

Exact prompt & config

1. Project config (.cursor/mcp.json) · Illustrative. Confirm the current Cursor key names in Settings > MCP > 'View config'.
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--isolated"]
    },
    "everything": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"]
    }
  }
}
2. Server that needs an env var · Pattern only. The package name is a placeholder; use the server your vendor currently documents (e.g. GitHub now publishes its own official MCP server).
{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["-y", "<vendor-mcp-package>"],
      "env": {
        "MY_API_TOKEN": "${env:MY_API_TOKEN}"
      }
    }
  }
}
3. Smoke-test prompt
Using only read-only MCP tools, call the playwright server:
navigate to https://example.com, take a snapshot, and tell me the page title and the text of the first <h1>.
Don't click anything. Don't use any write tools. If a tool asks for approval, stop and tell me which one.
4. Troubleshooting checklist
- Server red in MCP panel? Run the same command in a terminal: npx @playwright/mcp@latest --help
- Tools missing after edit? Click Refresh or restart Cursor.
- Works in terminal, not in Cursor? Cursor may not see the same PATH; use absolute paths to node/npx.
- Auth errors? Confirm the env var is set in the environment Cursor was launched from.

Sample output

Example output, written to show the expected shape. Not captured from a real run yet.

(Example of the expected shape, not a captured run)

MCP panel: playwright = connected (tools: browser_navigate, browser_snapshot, browser_click, …)
Smoke test: title "Example Domain", h1 "Example Domain". No write tools called.
Ready to add the next server.

Why project-level config

User-level MCP settings work for personal experiments. Anything the repo depends on (a browser smoke test, a docs server, an internal API) belongs in .cursor/mcp.json so every clone behaves the same. Secrets stay out of git; the config only names the env vars.

The loop that keeps you in control

  1. Add one read-only server.
  2. Confirm tools appear.
  3. Smoke-test with a harmless call.
  4. Then add write tools, with narrow tokens.
  5. Commit the config, document the env.

If you can’t explain what a tool is allowed to do, don’t enable it yet.

Going further

Once Playwright MCP works, use it in the flow from our Playwright MCP use case. The same pattern applies to Claude Code (claude mcp add …); keep both clients’ configs in the repo if the team mixes tools.

How it went

Pending test. What we expect, based on the vendor docs and public reports below. This becomes a measured result after our run.

Expected result, pending our test: with a current Cursor build the project mcp.json should connect on refresh, the smoke test should return the example.com title, and a missing env var should fail clearly rather than silently. We'll record the exact config shape Cursor expects on the version we test, any PATH issues, and how tool approval prompts behave.

Worth knowing

FAQ

What is MCP in Cursor?

Model Context Protocol: a standard way for Cursor's agent to call external tools (browsers, APIs, databases) through small local servers you configure.

Where do I put the Cursor MCP config?

In Settings > MCP for a user-level server, or in .cursor/mcp.json in the project so the team shares it. Prefer the project file for repo-specific tools.

Why is my MCP server not showing tools?

Usually a bad command/PATH, a missing dependency, or Cursor needing a refresh/restart. Run the same command in a terminal to see the error.

Is it safe to give Cursor access to GitHub or my database via MCP?

Only with least privilege: read-only tokens, no production write access, and tool approval enabled. Treat anything the tools return as untrusted.

Related use cases