Claude Code MCP Servers: The Complete Setup Guide

What the Model Context Protocol actually is

The Model Context Protocol (MCP) is an open standard for connecting AI applications to the tools and data they need to do useful work. Instead of every assistant hard-coding its own integration for Postgres, GitHub, or a headless browser, MCP defines one common language that any client can speak and any server can implement. Claude Code is an MCP client. An MCP server is a small program that exposes some capability — querying a database, driving a browser, reading your issue tracker — in that shared format.

Each server can expose three kinds of primitives. Tools are actions the model can invoke, like run_query or navigate. Resources are readable context, such as a file, a schema, or a log stream. Prompts are reusable templates the server offers to the client. In practice, most of what makes Claude Code more capable comes from tools: once a server is connected, Claude can call its tools during a session the same way it uses built-in file editing or shell access.

The payoff is that Claude Code stops being limited to the files in your working directory. It can read the actual rows in your staging database, open a real page and inspect the rendered DOM, or pull the current documentation for a library instead of guessing from training data. That is the difference between an assistant that writes plausible code and one that works against your real systems.

How MCP servers extend Claude Code

When you attach a server, Claude Code discovers its tools at startup and makes them available for the model to call. A few concrete examples of what teams wire up:

• Databases — inspect schemas, run read-only queries, and reason about data without you copy-pasting table definitions into the chat.
• Browser automation — navigate pages, click elements, fill forms, and take snapshots so Claude can verify a UI change actually renders instead of assuming it does.
• Documentation and search — fetch current, version-accurate docs for a framework so generated code matches the API that exists today.
• Developer platforms — read pull requests, issues, error reports, and CI status directly from the services where that context already lives.

MCP servers pair naturally with the rest of the Claude Code ecosystem. A subagent from the agents catalog can be scoped to use a specific database server; a lifecycle hook can run checks after Claude touches files a server helped it understand. Browse the full set of connectors on the MCP servers hub, and see how the pieces fit together from the Claude Code catalog home.

Configuring servers with .mcp.json

Claude Code reads MCP configuration from three scopes, which control who can see a server and where the config lives:

• Local (default) — private to you, in this one project. Good for experiments and personal credentials.
• Project — written to a .mcp.json file at the repository root and committed to version control, so every teammate gets the same servers.
• User — available across all of your projects on this machine.

The project scope is the one most teams standardize on, because the config travels with the repo. A .mcp.json file is plain JSON with a top-level mcpServers object. Here is a realistic file that wires up a local Postgres server, a browser automation server, and a remote error-tracking server:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost:5432/app"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

Notice that the first two entries launch a local process with command and args, while the third points at a remote URL with a type. Never hard-code secrets in a committed file. Claude Code expands environment variables in .mcp.json using ${VAR} syntax (with an optional ${VAR:-default} fallback), so you can reference a connection string or token that lives in your shell instead of the repo.

Understanding MCP transports

A transport is simply how Claude Code talks to the server. There are three, and choosing correctly avoids most connection headaches:

• stdio — Claude Code spawns the server as a local child process and communicates over standard input and output. This is the default for anything running on your own machine (the Postgres and Playwright entries above). It is fast, needs no network, and keeps data local.
• HTTP — the modern transport for remote servers, using streamable HTTP request/response. Use it for hosted services you connect to over the network; set "type": "http" and a url.
• SSE — an older Server-Sent Events transport for remote servers. It still works and you will see it in the wild, but new hosted servers are moving to streamable HTTP.

Rule of thumb: if the server runs on your laptop, use stdio; if it lives behind a URL, use HTTP. Remote transports frequently require authentication — Claude Code supports OAuth for servers that need it, and prompts you to sign in the first time a tool is called.

Popular MCP servers worth installing

You do not need dozens of servers. Most developers get real leverage from a handful:

• PostgreSQL — let Claude read your schema and run queries so it writes migrations and ORM code that match reality.
• Playwright — give Claude a real browser to navigate, interact with, and screenshot, which turns "I think this renders" into verified behavior.
• Context7 — pull current, version-specific library documentation into context so generated calls use APIs that actually exist.
• GitHub — read issues, pull requests, and CI status without leaving the terminal.

Each of these has a dedicated page on the MCP servers hub with its exact command, required environment variables, and the tools it exposes. Start with one database server and one browser server; add the rest only when a task demands it, because every connected server adds tools that compete for the model's attention.

Installing MCP servers the fast way

Hand-writing .mcp.json is fine, but the quickest path is the ToolZip installer, which pulls a curated, ready-to-run configuration and drops it into your project. Every MCP entry in the catalog installs with a single command:

# Install a curated MCP server from ToolZip
npx claude-code-templates@latest --mcp="database/postgresql" --yes

# Wire one up manually with the Claude Code CLI instead
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres "postgresql://localhost:5432/app"

# Add a remote server over HTTP at project scope so teammates inherit it
claude mcp add --transport http --scope project sentry https://mcp.sentry.dev/mcp

The --mcp="category/name" flag mirrors the path structure of the catalog, so database/postgresql maps straight to its component page. Swap the flag to install other component types — --agent, --command, --hook, --skill, or --setting — from the same tool. Explore the matching commands and skills hubs to round out your setup.

Managing, debugging, and securing servers

Once servers are configured, a few commands keep things healthy. Run claude mcp list in your terminal to see every configured server and its scope. Inside an interactive Claude Code session, type /mcp to view live connection status, inspect available tools, and trigger OAuth sign-in for remote servers. If a server fails to connect, the usual culprits are a missing environment variable, a wrong transport type, or a command that is not on your PATH — check those first.

Security deserves real attention. An MCP server is code you are granting access to your tools and, often, your data. Treat it like any dependency:

• Prefer servers you can inspect, and pin versions rather than always pulling latest for anything sensitive.
• Scope database credentials to read-only where possible, and keep them in environment variables, never in committed config.
• Use project scope deliberately — anything in .mcp.json is shared with everyone who clones the repo.
• Review which tools a server exposes before letting an autonomous agent call them without confirmation.

Configured well, MCP turns Claude Code from a smart text editor into an assistant that operates against your real stack — querying live data, driving a browser, and reading current docs. Pick two or three servers that match your daily work, commit a clean .mcp.json, and expand from there. Start browsing at the MCP servers catalog.