Connecting an MCP server to Claude Code

What MCP actually adds

The Model Context Protocol gives Claude Code a standard way to reach tools and data that live outside your repository — a database, an internal API, a ticketing system, a design tool — without you writing a bespoke integration for each one. Once a server is connected, its tools show up alongside Claude Code's built-in ones and get called the same way: Claude decides when to use them based on the task, not because you invoked a special command.

This is worth understanding before you connect your first server, because the failure modes are almost entirely about scope and trust rather than protocol mechanics. An MCP server is code running with real access to whatever it's configured against — a database server with write access, a ticketing server that can create and close issues — and Claude Code will call it the same way it calls any other tool, which means a poorly scoped server is a real risk, not a hypothetical one.

Adding a server

MCP servers are configured per-project or globally, and a server is defined by how Claude Code should run it: usually a command, its arguments, and any environment variables the server needs (API keys, connection strings). Once configured, restart Claude Code and check that the server appears as connected — a misconfigured command or a missing environment variable is by far the most common reason a server silently never loads. If a server you expect to see isn't listed, that is almost always where to look first, before assuming the server itself is broken.

Scoping what the server can actually do

The single most important decision when connecting a server is not whether to connect it, but what it's allowed to touch. A database MCP server pointed at a production connection string with write access turns every Claude Code session into something that can modify production data — worth doing deliberately, and almost never worth doing by default. Prefer read-only credentials wherever the server supports them, and prefer a scoped or staging environment over production unless you have a specific reason to need production access in that session.

Claude Code's permission system applies to MCP tool calls the same way it applies to file edits and shell commands: you can require confirmation before a specific tool runs, or allow it automatically once you've reviewed what it does. For a server with any write capability, start with confirmation required and only relax it once you've watched it behave correctly across a few real sessions — loosening a permission is reversible in a way that an unwanted write to a shared system is not.

A minimal server entry

A server definition is small — a command, its arguments, and whatever environment it needs:

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "env": { "EXAMPLE_API_KEY": "..." }
    }
  }
}

Debugging a server that won't connect

Three things account for nearly every connection failure, roughly in order of how often each one turns out to be the culprit:

• The command Claude Code is configured to run isn't actually on the PATH it runs with — this bites often on machines where a tool is installed via a version manager that isn't active in a non-interactive shell.
• A required environment variable is missing or malformed, which usually surfaces as the server starting and then immediately exiting rather than a clear "missing credential" message.
• The server process starts but never responds on the protocol Claude Code expects, which usually means a version mismatch between the server and what Claude Code's MCP client supports.

Checking the server's own logs, where it's configured to produce them, resolves the third case far faster than guessing at a protocol mismatch from the outside.

What doesn't need MCP

Not every integration needs a server. If you just need Claude Code to read from or write to a REST API a handful of times, a direct HTTP call inside a script Claude Code runs is often simpler to reason about and debug than standing up a full MCP server for a one-off task. MCP earns its complexity when the same tool gets reused across many sessions and many people, or when the underlying system genuinely benefits from Claude having structured, repeatable access to it rather than an ad hoc call.

Terminal and editor context

If you're driving Claude Code from a terminal multiplexer or an editor you're still learning the keybindings for, that's a separate but related friction point — AltPlusCtrl keeps a practice-driven reference for exactly that, for the editors and terminals developers actually pair Claude Code with.