How to Connect Claude Code and Cursor to Local MCP Servers: A Step-by-Step Guide

A local MCP server is just a process running on your own machine that Claude Code or Cursor talks to over stdin and stdout. No network, no auth, no shared infrastructure. That makes it the right starting point when you're building a server yourself, or connecting to something like a local database or file system that only makes sense on your machine.

Here's how to actually wire that up in both tools, where it breaks, and what the errors are actually telling you.

What "local" means here, and why it works this way

When you add a local (stdio) server, the client spawns your server as a child process. It writes JSON-RPC requests to that process's stdin and reads responses from its stdout. Anything the server logs goes to stderr, which the client captures separately so it doesn't corrupt the JSON-RPC stream. According to Claude Code's own docs, this is the recommended transport for anything that only needs to run on your machine, with HTTP reserved for servers other people or other machines need to reach.

The tradeoff that matters: a stdio server only exists while that specific process is running, on that specific machine. There's no way to share a running instance across a team. Every developer who wants the same server spins up their own copy.

Setting it up in Claude Code

Register a server with:

claude mcp add --transport stdio my-server -- node my-server.js

Claude Code supports three scopes for this, and picking the wrong one is a common source of "why doesn't my teammate see this server" confusion:

• local (the default): stored in your personal settings, not shared with anyone.
• project (--scope project): written to a .mcp.json file at your project root, which you commit to git so everyone on the repo gets the same config.
• user: available to you across every project on your machine.

One detail that trips people up moving between Claude's own apps: Claude Code requires an explicit "type": "stdio" field in .mcp.json, where Claude Desktop infers stdio automatically just from the presence of a command field. Copying a working Claude Desktop config straight into Claude Code's .mcp.json without adding that field is a real, easy-to-hit failure mode.

To pass secrets or config to the server process, use -e:

claude mcp add --transport stdio my-server -e API_KEY=your-key -- node my-server.js

If you use --scope project, remember that file gets committed. Put secrets in your own environment, not in the committed config.

Setting it up in Cursor

Cursor reads its MCP config from .cursor/mcp.json for a project, or ~/.cursor/mcp.json globally. Not .vscode/mcp.json, and not a bare mcp.json at the repo root; both are dead ends that produce no server and no error telling you why.

The single most common failure here, according to a troubleshooting breakdown covering Cursor, VS Code, and Claude Desktop, isn't a broken command or a bad path. It's the top-level key in the JSON file. Cursor expects mcpServers. An older or mistyped key name produces a file that's still valid JSON, so Cursor doesn't complain, it just silently loads nothing.

The second most common failure is JSON syntax itself: a trailing comma after the last server entry, or a missing comma between two entries. Cursor doesn't surface a parse error in the UI for this either. If a server isn't showing up and the config looks right at a glance, paste the file into any JSON validator before you touch anything else.

Two more from that same breakdown worth checking before you assume the server itself is broken:

• The workspace root Cursor thinks it's in doesn't match where you put .cursor/mcp.json. This happens most often when you open a subdirectory of a monorepo as the workspace instead of its root.
• You edited the config but never restarted the IDE. MCP config in Cursor is read at startup, not live-reloaded.

Quick answers to what people actually get stuck on

Why isn't my server showing up after I added it correctly? Restart the IDE completely. This alone resolves the large majority of cases that look like a broken server but are actually a stale client that hasn't re-read the config.

Do I need to restart every time I change the config? Yes, for both tools, this isn't optional.

stdio or HTTP, which do I actually need? stdio for anything that only runs on your machine (a script, a local dev database). HTTP for anything a teammate, a CI job, or a remote agent needs to reach too.

Can I just point my whole team at the stdio server running on my laptop? No. Nothing about stdio makes that possible, and nothing about MCP's design tries to. If your team needs shared access to the same server, that's a signal to build (or connect to) an HTTP server, not a local one.

Beyond Claude Code and Cursor

Claude Code and Cursor are MCP hosts, but they're not the only ones. If you're experimenting outside either tool, two projects come up often: Nanobot is a standalone, self-hosted MCP host that turns a set of MCP servers into an agent you can run yourself, serving over HTTP on localhost by default rather than requiring an IDE. iFlow CLI is a terminal-based coding agent with its own MCP client, aimed at the same "point an agent at your repo" use case as Claude Code, with its own package ecosystem for installing MCP tools. Neither replaces Claude Code or Cursor for day-to-day IDE work, but they're worth knowing if you're building or testing an MCP server independent of any single client.

When one local server per developer stops being enough

The moment you need the same server state shared across a team, or you need to know which teammate (or agent) made a given change, a stdio server on someone's laptop can't do that by design. That's also exactly the point where hand-rolling your own auth and access control on top of a plain HTTP server gets expensive. Building a project management MCP server walks through what that actually takes: scoped tokens, rate limits, safe concurrent writes.

If you'd rather skip building that layer yourself, connecting Cursor or Claude Code to TAM gives you the same local setup experience, just pointed at a server your whole team already shares.