Hey, I'm Lena. Something clicked for me a few weeks ago, and I've been trying to figure out why it took so long.

I'd been using Claude Code regularly — running shell commands, editing files, stepping through refactors. Useful, but still kind of siloed. Then I connected a GitHub MCP server and asked it to review a pull request, check for related Sentry errors, and update the Jira ticket. One session. Three services. It worked.

That's when it stopped feeling like a smart terminal wrapper and started feeling like something more composable. This guide is what I wish I'd had before I spent two hours reading fragmented docs and GitHub issues to get there.

How MCP Works Inside Claude Code

Claude Code is an MCP client. That distinction matters. On its own, it can read files, run bash commands, search code, and call the Anthropic API. That's already a lot. But it can't touch your GitHub repos, your Postgres tables, or your Figma frames without something connecting them.

That something is MCP — an open source standard for AI-tool integrations. When you add an MCP server, Claude Code gets access to new tools: querying a database, reading Jira tickets, or interacting with external services.

How Claude Code handles tool calls

When Claude Code decides it needs to call an MCP tool, it doesn't just fire it off. Claude Code displays a permission prompt before calling any MCP tool — showing the tool name and its input arguments so you can review what it's about to do before it executes.

Tool names follow a structured format: mcp__<server-name>__<tool-name>. So the filesystem server's read tool becomes mcp__filesystem__read_file. That naming convention matters if you're pre-approving tools in headless or CI environments.

What MCP adds that built-in tools don't

Claude Code's native tools handle local environments well. What they don't do: reach external services, query databases, or pull from issue trackers. MCP extends that reach by connecting it to external tools and services — each server gives Claude Code a new set of capabilities: query a database, create a GitHub issue, run a browser test, or fetch design tokens from Figma.

The Model Context Protocol specification defines three core primitives: Resources (raw data), Tools (actions), and Prompts (reusable templates). In practice, tools are what you'll interact with most.

How to Install and Configure MCP Servers in Claude Code

Finding the MCP config location

There are two main places Claude Code stores MCP configuration:

Project scope — .mcp.json in your project directory, version-controlled, shared with your team
User scope — your user settings, available across all projects

Project-specific overrides also live in .claude/settings.local.json and ~/.claude/settings.local.json for user-specific local settings.

For most solo developers, the user scope is the more practical default. For team setups, .mcp.json is what you want — it commits with the repo.

Adding a server entry

The primary method is the claude mcp add command. HTTP servers are the recommended option for remote MCP servers and are the most widely supported transport for cloud-based services:

Bash

# Remote HTTP server (recommended for cloud services)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Local stdio server (for tools needing direct system access)
claude mcp add --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem /home/user/projects

# User-scoped (available across all projects)
claude mcp add --scope user my-db -- npx -y @my-org/mcp-server-postgres

One thing that trips people up: all options (--transport, --env, --scope) must come before the server name. The -- separates the server name from the command arguments. Get that order wrong and the flags get passed to the wrong process.

If you're on Windows, wrap npx commands with cmd /c:

Bash

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Without the cmd /c wrapper, Windows can't execute npx directly and throws "Connection closed."

Verifying the connection

After adding a server, run:

Bash

claude mcp list

Inside a Claude Code session, use /mcp to open the management panel and check server status. You'll see connected, disconnected, or error states per server.

Testing tool calls in a session

Once a server shows as connected, just ask Claude Code to use it. Something like: *"Read the file at /home/user/projects/config.json"* after adding the filesystem server. If configured correctly, you'll see the permission prompt appear before Claude Code executes.

Worth noting: MCP configuration changes with Claude Code updates. The official Claude Code MCP documentation is the authoritative reference — check it if behavior diverges from what's described here.

Recommended MCP Servers for Claude Code

These are servers I've seen behave reliably, based on what's maintained as of early 2026. The official MCP servers repository on GitHub has the full list — some are Anthropic-maintained, most are community-built.

Filesystem — The foundational one. Reads, writes, and organizes local files with configurable directory boundaries. You control which directories are exposed.

Bash

claude mcp add --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem /your/project/path

GitHub — Add the GitHub MCP server with a personal access token via HTTP transport:

Bash

claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'

This gives Claude Code access to PRs, issues, and repositories. Useful for asking things like "Review the diff in PR #234 and leave inline comments."

PostgreSQL — Lets Claude query your database directly. Set your connection string as an environment variable:

Bash

claude mcp add --scope user my-db -- npx -y @modelcontextprotocol/server-postgres
# Set DATABASE_URL in your environment

Web search / Fetch — Firecrawl MCP fetches URLs and returns clean Markdown. Useful when Claude needs current API docs or third-party references that aren't in its training data.

Context7 — Retrieves version-specific library documentation. Particularly useful when you're working with a framework version that Claude doesn't have clean training data for.

Sequential Thinking — Not a data source, but a reasoning server. Helps Claude break down complex refactoring tasks into explicit steps before executing them.

One honest caveat: use third-party MCP servers carefully. Anthropic has not verified the correctness or security of all MCP servers. Be especially careful with servers that fetch untrusted content, as these can expose you to prompt injection risk.

Troubleshooting MCP in Claude Code

Server not appearing

The most common cause: PATH issues. Claude Code launches MCP server subprocesses with a different shell environment than your terminal, so tools like node and npx may not be found. If you use nvm, either use absolute paths to the Node binary, or ensure nvm loads in non-interactive shells by adding the nvm initialization block to your shell profile.

Also validate your JSON. Trailing commas, missing quotes, and unescaped backslashes cause silent failures — JSON doesn't allow trailing commas, and this is one of the most common mistakes in MCP config files. Run your config through a JSON linter before restarting.

Tool calls returning errors

If a server connects but tool calls fail, check that the tool name format matches: mcp__<server-name>__<tool-name>. Also, check that the environment variables (API keys, connection strings) are actually set in your shell — Claude Code inherits them from the process environment, not from your .env file automatically.

For SSE transport issues: the MCP_TIMEOUT environment variable doesn't apply to SSE connections — switch to HTTP transport, which is more reliable and recommended by the official docs.

Beyond MCP: Making Claude Code's Work Reusable

Here's something I keep thinking about. MCP solves the reach problem — Claude Code can now touch GitHub, databases, Slack. But each session still starts from scratch. The fixes Claude figures out, the patterns it identifies, the successful approaches it takes — those don't carry forward automatically.

That gap between "Claude did something useful" and "that useful thing is now part of how my system works" is real, and it's separate from what MCP addresses.

For now, the practical workaround is explicit: use CLAUDE.md files to document patterns Claude should reuse, commit good prompts alongside code, and treat successful Claude Code sessions as something worth capturing — not just consuming.

FAQ

How do I add MCP servers to Claude Code?

Run claude mcp add with the appropriate transport flag. For remote services, use --transport http. For local tools, use --transport stdio. Scope the server to your project with --scope project or to your user profile with --scope user. Full syntax and examples are in the official Claude Code MCP docs.

Where is the MCP config file in Claude Code?

Project-scoped configs live in .mcp.json at your project root. User-scoped configs are in your Claude Code user settings. You can also edit ~/.claude.json directly for more complex configurations — just validate the JSON before restarting.

Which MCP servers work best with Claude Code?

For most developers: the GitHub MCP server and filesystem server cover the highest-frequency cases. Add PostgreSQL if you're querying databases regularly. Context7 is worth the setup for documentation-heavy work. Sequential Thinking helps with complex multi-step refactors. Start with one or two, verify they connect cleanly, then expand.

I'll keep watching how this stack evolves. The list above reflects what's actually maintained and usable as of early 2026 — not what sounds good in theory.