Claude Code MCP: How to Add and Use MCP Servers
Claude Code MCP is the Model Context Protocol support built into the Claude Code CLI, which lets the agent discover and call external tools through one standard interface instead of a bespoke integration per tool. You add a server with the claude mcp add command, point it at an executable, and the agent lists that server's tools at startup and calls them by name when it needs them.
Most MCP writeups stay abstract and leave you no wiser about what actually happens on your machine. The useful version is concrete: a server advertises named tools, Claude Code discovers them, and the model decides when to use one.
What is Claude Code MCP and why should you care?
Claude Code is an agent that already reads files, runs commands, and edits your repo. MCP is how you extend that reach to things outside the working directory without writing model-specific code.
Before MCP, every integration was a one-off. If you wanted the agent to query Postgres, read Linear, or see your screen, someone wrote a Claude-specific adapter for each. Claude Code MCP removes that N-by-M glue problem by standardizing the contract between the agent and any tool.
A server exposes three kinds of capability: tools (functions the model calls, with typed arguments), resources (readable data pulled in as context), and prompts (reusable templates). In practice, tools are what you reach for most.
MCP standardizes the contract, not the intelligence. The server says "here are my tools and their argument schemas"; the model decides which to call and with what values. That split is why one server works across Claude Code, Cursor, and other clients.
The payoff is compounding. Every well-built server you add is a new capability the agent can use forever, and the same server works in any MCP client, so nothing is wasted if you switch tools later.
How do you add an MCP server to Claude Code?
The core command is short. From your project you run:
claude mcp add pinvariThat registers the server and its startup command. Servers can be scoped to a project (stored in that repo's config) or made available across all your projects, and Claude Code reads both at launch. For the full flag reference and scoping options, see claude mcp add.
Once added, verify it. Inside Claude Code, ask what tools are available or run the MCP status view; the server should appear with its tools listed. If it does, the handshake worked and the model can now call those tools.
The lifecycle under the hood is plain JSON-RPC. Claude Code launches the server, sends initialize, the server returns its capabilities, and the client calls tools/list. During a session the model chooses a tool, the client sends tools/call, and the server does the work and returns a structured result.
Run a new server by hand once before wiring it into Claude Code. If it starts and prints its capabilities in your terminal, any later failure is almost always the config path, not the code. This one habit saves most debugging time.
That is the whole loop. You are not teaching the model a new API; you are giving it a menu it discovers automatically.
What can a local MCP server actually do on a Mac?
Here is the concrete example the docs skip. A local MCP server runs on 127.0.0.1, so it can reach things a hosted tool never could, like the live state of your screen, and it can do it without uploading anything.
PinVari is a native macOS server of exactly this kind. You hold ⌥⌘A, circle or point at a UI element, and speak. It screenshots, transcribes on-device, and resolves the exact accessibility element you circled, its role, label, and frame, with a confidence score, then exposes that to Claude Code as a tool.
The agent-facing tool is pinvari_next_instruction. It returns the resolved element path, the spoken instruction, the region you circled, and a screenshot cropped to that region; pinvari_mark_done closes it out. The agent receives a named element it can act on, not a screenshot it has to decode.
That is the general lesson for any good MCP server. It should not just relay raw data; it should resolve meaning on your side and hand the agent something already structured. A screenshot server ships pixels; a context server ships a named element the agent can trust. The fuller argument is in how a local MCP server gives an agent screen context and why screenshots are the wrong primitive for telling an agent what you mean.
The resolution is honest about hard cases. When a point lands on a bare AXGroup, it descends to the deepest labeled child; on Chromium and Electron surfaces that build their accessibility tree lazily, it sets AXManualAccessibility and retries until a labeled node appears; on a canvas with no AX tree, it falls back to on-device Vision OCR. Below a confidence bar, it asks rather than guessing silently.
Everything in that flow stays on-device. Transcription and OCR use Apple frameworks, there are no API keys, and nothing is uploaded by default. You bring your own agent and model.
Claude Code MCP vs Cursor MCP: what is different?
Both support MCP, and a server you build works in either. The differences are in the client, not the protocol.
| Aspect | Claude Code | Cursor |
|---|---|---|
| Form factor | Terminal CLI | AI-native editor |
| Add a server | claude mcp add | JSON config in settings |
| Server scope | Project or global | Per-project or global config |
| Transport | stdio and HTTP | stdio and HTTP |
| Best fit | Terminal-first, scripting | Editor-first workflow |
Because the protocol is shared, the choice between them is about how you like to work, not about which servers you can run. The same PinVari server, the same git server, the same database server all plug into either. If you are weighing the two more broadly, the Claude Code vs Cursor trade-offs come down to terminal versus editor more than raw capability.
The practical upshot: pick your client for ergonomics, and treat your MCP servers as portable infrastructure that follows you across tools. If your team standardizes on a shared set of servers, everyone gets the same capabilities whether they run Claude Code in a terminal or Cursor in an editor, and onboarding a new machine is one config file rather than a day of setup.
Why is my MCP server not showing up in Claude Code?
Nine times out of ten it is the config, not the code. The server points at the wrong executable, the command does not actually start, or the JSON has a typo that silently drops the entry.
Work through it in order. Confirm the server runs standalone in your terminal. Confirm the path in your config is absolute and correct. Restart Claude Code so it re-reads the config. Then check the MCP status view to see whether the server connected and whether it errored on initialize.
A server that appears but lists zero tools usually failed after initialize but before advertising its tools. Read its stderr. On lazy surfaces or slow startups, a timeout can cut the handshake short before tools register.
If it still refuses to appear, the step-by-step recovery is in why your Claude Code MCP server is not working. Most fixes are a corrected path or a restart, not a code change.
If a screen-context server is the piece you are missing on a Mac, PinVari is a one-time purchase rather than a subscription, and the setup and details are on the pricing page.
FAQ
What does MCP stand for in Claude Code?
MCP stands for Model Context Protocol, an open standard for connecting an AI agent to external tools and data through one uniform interface. Claude Code acts as the MCP client, discovering and calling tools that MCP servers expose.
How do I add an MCP server to Claude Code?
Run claude mcp add <name> and point it at the server's startup command, or edit the MCP config directly for finer control over scope. Restart Claude Code, then confirm the server and its tools appear in the MCP status view before using it.
Is Claude Code MCP the same as Cursor MCP?
The protocol is identical, so a server built for one works in the other. The difference is the client: Claude Code is a terminal CLI configured with claude mcp add, while Cursor is an editor configured through its settings JSON.
Can an MCP server run locally without an internet connection?
Yes. A local MCP server runs on 127.0.0.1 as a child process over stdio, so it never needs the network. On a Mac, a local server can gather screen context, transcription, and OCR entirely on-device.
Why does Claude Code say my MCP server failed to connect?
Usually the config points at the wrong executable, the server crashes on startup, or the handshake times out. Run the server by hand first, use an absolute path in the config, restart Claude Code, and read the server's stderr to see where initialize stopped.
Do I need an API key to use Claude Code MCP?
Not for the protocol itself. Some servers wrap paid APIs and need their own keys, but a local server like a filesystem or screen-context server runs entirely on your machine with no key and no upload.
Hand your agent the exact element
PinVari resolves what you point at into a named, executable instruction — on-device, no keys, your own agent. If you run Claude Code, it is one command.
claude mcp add pinvariGet PinVari — $39 →
