That approval step is where most setups appear broken. The config is right, the server runs, and no tools show because nobody clicked.

Where does Cursor look for MCP config?

Two files, two scopes:

If both exist, project-level entries merge with global ones and project takes precedence on name collisions. Name servers distinctly — a global postgres and a project postgres with different connection strings is a debugging afternoon you don’t want.

Step 1: Add the server block

Here is a minimal per-project config with an API key passed as an environment variable:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "env": {}
    },
    "internal-api": {
      "command": "node",
      "args": ["./mcp-server/dist/index.js"],
      "env": { "API_TOKEN": "paste-token-here" }
    }
  }
}

The . in the filesystem args means “current working directory” — scoped to the project, which is what you want. Never point it at ~.

Step 2: Restart, then enable the tools

Completely quit Cursor and reopen the project. Open the agent panel and look at the tool list — there’s an MCP section where each server shows its tools with individual toggles.

Enable the ones you need. Cursor keeps them disabled by default for a reason: a filesystem server with 11 tools adds 11 function definitions to every request, which costs tokens and dilutes tool selection. Enable three tools and the model picks correctly more often than when all 11 are on.

Step 3: Watch the output for startup errors

Cursor surfaces MCP stderr in the Output pane under the MCP channel. Two errors that come up constantly:

• Server exited before handshake — usually a missing dependency. Run the exact command in your terminal; the real error appears there.
• Tool call failed with 401 — the env var didn’t reach the subprocess. Cursor passes env verbatim; if your server reads a config file instead, that file may be in the wrong working directory.

Relative paths in args resolve from the workspace root, not from the config file’s folder. That trips people up in monorepos.

Step 4: Decide what the agent is allowed to touch

MCP changes what the agent can do without approval. A Postgres server with write access in an agent that also runs terminal commands is a bad combination — one hallucinated query and a table is gone.

Practical rules that have served me well:

• Read-only database credentials for any MCP server in a coding agent
• Filesystem scope limited to the project folder
• No server with production credentials in a config file that lives in a repo you might push publicly
• .cursor/mcp.json in .gitignore if it contains tokens

Step 5: Write your own and test it as a project server

If you build a server, develop it inside the project and point Cursor at ./mcp-server/dist/index.js. Rebuild and restart Cursor to pick up changes — Cursor doesn’t hot reload MCP servers, which surprises people mid-session.

For quick iteration, run it in a terminal first and use the MCP Inspector to confirm it lists tools before wiring it into Cursor. Debugging through the editor’s output pane is slower.

Why do tools disappear after a Cursor update?

Because the tool approval state is tied to the server’s reported tool list. If your server changes its tools — added a parameter, renamed something — Cursor treats them as new and leaves them disabled. Re-enable them after any server update. This is also why version-pinning your MCP server package is worth the small hassle.

Should MCP servers be per-project or global?

The filesystem and shell-adjacent ones per-project, always. A global filesystem server pointed at your home directory means every project you open can read every other project. Database and API servers where the credentials differ per project belong in the project config; ones like a documentation search or a personal notes server work fine globally.

Quick Summary

• Project config lives at .cursor/mcp.json; global at ~/.cursor/mcp.json.
• Restart Cursor fully and enable each tool manually in the MCP panel.
• Give filesystem servers the project folder (.), never your home directory.
• Use read-only DB credentials; keep tokens out of committed config files.
• Tools reset to disabled when a server changes its tool list — re-enable after updates.

The hard part isn’t the code. It’s deciding how granular your tools should be.

What does a minimal MCP server contain?

Three things: a server instance with a name and version, one or more registered tools, and a transport to talk to the client. The @modelcontextprotocol/sdk package gives you all three. Python has an equivalent with mcp on PyPI and the FastMCP helper.

Nothing here requires Anthropic’s blessing or a manifest upload. The protocol is open and the client just spawns your process.

Step 1: Scaffold and install

mkdir my-mcp && cd my-mcp
npm init -y
npm i @modelcontextprotocol/sdk zod

Add "type": "module" to package.json and set a bin entry if you want to run it after npm link. You’ll be writing ESM whether you like it or not — the SDK ships ESM-only now, so CommonJS require will fail.

Step 2: Define tools by user intent, not by endpoint

The most common mistake is one tool per REST endpoint. Give a model 40 endpoints and it picks wrong constantly. Give it four tools that match how a person would ask, and accuracy climbs sharply.

Compare these two designs for an invoicing API:

Task-oriented tools need server-side logic. That’s fine — it’s your server.

Step 3: Write schemas the model can read

Every tool needs a name, a description that reads like an instruction, and an inputSchema in JSON Schema. Descriptions carry more weight than you’d expect: the model selects tools by matching the user’s words against them.

Write descriptions that include the trigger conditions. “Search invoices. Use when the user asks about billing history, overdue amounts, or a specific invoice number” beats “Search invoices” by a wide margin in my testing. Avoid clever names — find_invoices is better than invQ.

Use zod for validation. Mark required fields as required; models do respect required arrays, but only if you also reject bad input rather than coercing it.

Step 4: Handle errors as tool results, not exceptions

This is the item that separates a toy server from a usable one. If your handler throws, the client sees a transport error and the conversation stalls. Instead, return a result with isError: true and a message the model can act on.

Say the API returns 429. Return something like “Rate limited, retry after 30 seconds” rather than a stack trace. The model will wait or tell the user. A raw exception gets you a broken turn.

Also: never return a whole JSON blob if a short summary works. Token cost is real, and dumping 400 invoice rows fills the context window in one call. Paginate with a default page size of 20.

Step 5: Wire up stdio, then add to the client

const transport = new StdioServerTransport();
await server.connect(transport);

Stdio means the client launches your process and speaks over stdin/stdout. Two rules follow: never write logs to stdout (it corrupts the protocol — use stderr), and keep startup under a few seconds, because clients time out fast.

For local development, test in the MCP Inspector before wiring it into Claude Desktop. Build the config entry with command: "node" and args: ["/absolute/path/to/build/index.js"].

Should you use stdio or HTTP transport?

Stdio for anything local: it’s simpler, needs no auth, and dies when the client closes. HTTP with the streamable transport for anything shared across machines or served to a team. Multi-user HTTP needs real auth — an unauthenticated MCP endpoint exposed to the internet is an open door to whatever API keys you hold.

When is a custom server overkill?

If your need is one or two read-only calls, a script plus a paste beats a protocol. If you’re the only user and you never change editors, a shell alias works. Build a server when you want the same capability available in several MCP clients, or when teammates should reuse it without copying configs.

Quick Summary

• The official SDK scaffolds an MCP server in under 100 lines with stdio transport.
• Design 3-6 tools around user tasks, not one per API endpoint.
• Tool descriptions are prompts: include when to use the tool.
• Return errors as isError results with actionable text, never as thrown exceptions.
• Log to stderr only; anything on stdout breaks the protocol.

That’s the whole loop. The friction is entirely in the paths and the JSON.

What is MCP and why should you care?

MCP is a protocol that defines how an AI client asks a server what it can do, then calls those capabilities. Think of it as a USB port for AI: one server for your filesystem, one for Postgres, one for GitHub, and any MCP-speaking client can use all of them without custom code per app.

Claude Desktop, Cursor, and a growing list of editors speak MCP natively. Servers exist in Node and Python, and the reference ones live under modelcontextprotocol/servers on GitHub.

You need this if you keep copying data into chat windows by hand. You don’t need it if a plain API key plus a script already solves your problem.

Step 1: Find the config file (the part people get wrong)

The file is not inside the app bundle. It lives in your user profile:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

If the file doesn’t exist, create it. Claude Desktop will not generate it for you, and it silently ignores a file saved with a .txt extension — a surprisingly common cause of “nothing happened”.

Step 2: Install Node 18 or newer first

Most reference servers are npm packages run through npx. Check with node -v. Anything below 18 fails on modern syntax, and on Windows you’ll want the plain node install rather than a version manager shim, because Claude Desktop launches the process without your shell’s PATH.

That PATH detail explains half of all broken setups: the app can find node interactively but not when it spawns the server. If npx isn’t on the system path, use an absolute path like /usr/local/bin/npx or C:\\Program Files\\nodejs\\npx.cmd.

Step 3: Add your first server

Open the config and paste this, adjusting the folder to one you actually want readable:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/Projects"
      ]
    }
  }
}

Three rules: the top key must be mcpServers, every entry needs command, and on Windows command must be npx.cmd not npx. Save as UTF-8 with no BOM.

Step 4: Restart completely, not just the window

Quit Claude Desktop from the menu — on macOS Cmd+Q, not the red close button. The app only reads the config file at process start. After relaunch, look for a small plug icon or a tools badge in the message input; hovering shows which server it is and how many tools it exposes. The filesystem server typically reports 11 tools.

If the icon is missing entirely, the config didn’t parse. Validate it with python3 -m json.tool claude_desktop_config.json before doing anything else.

Step 5: Test with a request that proves file access

Ask: “List the files in my Projects folder and summarise any README.” Claude will request permission the first time — approval is per-client, not per-session. Deny it and the tool stays unavailable until you flip it back in settings.

Good first tests are cheap and verifiable. “What’s in package.json?” beats “organise my whole drive”, which burns context and usually disappoints.

How do you debug a server that won’t start?

Enable the log file and read it. On macOS, tail ~/Library/Logs/Claude/ and open the file named for your server (logs are written per server). On Windows it’s under %APPDATA%\Claude\logs. You want the last error, not the whole file.

The two failures I see most:

• spawn npx ENOENT — the PATH problem above. Use an absolute command path.
• Server disconnected after a few seconds — usually a crashed package. Run the exact command + args in your terminal and watch the error appear immediately.

Is running MCP servers risky?

Yes, in a specific way: the filesystem server can read whatever path you give it, and some community servers accept arbitrary shell commands. Scope directories narrowly. Give the filesystem server your Projects folder, never your home directory. Review any third-party server’s source before pointing it at credentials — you’re handing a model the keys.

Quick Summary

• MCP connects Claude Desktop to local tools through claude_desktop_config.json.
• The file lives in the user profile, not the app folder, and must be UTF-8 JSON.
• Node 18+ is required; use absolute paths to npx to avoid the PATH error.
• Fully quit and relaunch the app — the config is read at startup only.
• Scope filesystem servers to specific folders, not your whole home directory.