If you’ve used Claude code mcp for more than a day, you already know the feeling. You’re in the middle of a task, and you think, wouldn’t it be useful if Claude could just pull from my database right now? Or check that GitHub PR without me copying and pasting? That’s exactly what MCP makes possible, and the setup is less painful than most people expect.
MCP stands for Model Context Protocol. It’s an open standard that allows Claude Code to interact with external tools, APIs, and data sources. You can think of it as giving Claude a set of hands to reach into tools like Sentry, Notion, GitHub, PostgreSQL, or anything else you already use.
This connection is made through an MCP server, a lightweight process that sits between Claude Code and the tools you want it to access.
What I appreciate about how Anthropic built this is that you’re not locked into one approach. You can connect remote servers over HTTP, run local tools as stdio processes, or share configurations across your entire team through a single file. Let me walk you through how it all works.
[IMAGE: Claude Code MCP server connection diagram showing Claude Code linked to GitHub, Sentry, and a database]
What claude code mcp actually does in practice
Before getting into the setup, it helps to understand what you’re actually enabling. When a Claude Code MCP server is connected, Claude Code can act on your behalf across systems it wouldn’t otherwise have access to.
Here’s a practical example. Let’s say your team uses Sentry to track bugs and Jira to manage tasks. Without MCP, the workflow is pretty manual you copy an error from Sentry, paste it somewhere, write out the Jira ticket yourself, and then ask Claude Code to help with a fix.
With MCP set up, it’s a different experience. You can give a single instruction like, “Check Sentry for errors from the latest deployment and create Jira tickets for anything critical,” and Claude handles the rest.
I’ve seen teams use this to query production databases without writing custom scripts, automate Gmail drafts for user outreach, and pull Figma designs directly into a code update task. The range is wide, and it grows as more MCP servers become available.
One thing worth knowing early: Anthropic hasn’t verified the security of every third-party MCP server. Use servers you trust, especially any that touch live databases or can fetch external content. That’s not a knock against the ecosystem; it’s just good practice.
[INTERNAL LINK: getting started with Claude Code for your first project]
Understanding the claude code mcp config options
There are three ways to add an MCP server, and the one you choose depends on what you’re connecting to.
Remote HTTP servers are the recommended path for cloud-based services. Tools like Notion, GitHub, Sentry, HubSpot, and Stripe all offer HTTP-based MCP endpoints. You point Claude Code at the URL, optionally add an auth header, and you’re connected.
SSE (Server-Sent Events) is the older transport method. It still works for tools like Asana that haven’t moved to HTTP yet, but it’s deprecated, meaning it’ll eventually be replaced. If you have a choice, use HTTP.
Local stdio servers run as processes directly on your machine. These are useful for database connections, custom scripts, or any tool that requires direct system access. Airtable’s MCP server works this way, for instance. You pass in your API key as an environment variable, give it a name, and Claude Code manages the process.
The Claude MCP add command is the entry point for all three. You specify the transport type, give the server a name, and point it at either a URL or a local command. Options like –env for environment variables and –header for auth headers give you control without having to edit anything manually.
| Transport type | Best for | Auto-updates |
|---|---|---|
| HTTP | Cloud APIs, SaaS tools, remote services | Yes |
| SSE | Legacy tools not yet on HTTP (e.g. Asana) | Yes |
| Stdio | Local tools, databases, custom scripts | No — runs locally |
One Windows-specific detail to keep in mind: if you’re running on native Windows (not WSL) and setting up a stdio server that uses npx, you’ll need to wrap the command with cmd /c.
Without that, you’ll likely run into “Connection closed” errors, since Windows can’t execute npx directly in this context. It’s a common issue but an easy fix once you know what’s causing it.
The claude code mcp config file and scope explained
This is the part that confuses people most. Claude Code stores MCP configurations in different places depending on scope, and understanding the three scope levels saves a lot of head-scratching later.
Local scope is the default. It stores the server config in ~/.claude.json and keeps it private to your current project. It’s the right choice for experimental setups, personal API keys, or anything you don’t want shared with teammates.
The project scope is for team sharing. When you add a server with –scope project, Claude Code creates or updates a .mcp.json file in your project’s root directory. That file is designed to be committed to version control, so everyone on the team gets the same server configuration when they pull the project. This is my preferred setup for anything team-facing.
User scope stores the config in ~/.claude.json and makes it available across all your projects. Useful for personal utility servers you reach for constantly, like a database tool or a GitHub connection you use everywhere.
[IMAGE: Claude Code MCP config file scope diagram showing local, project, and user scope storage paths]
Setting up the claude code mcp server config file for a team
When you commit a .mcp.json to version control, your teammates get the same MCP tools without any individual setup. The file follows a clean JSON structure: a top-level mcpServers key, then each server as a named object with its command, arguments, and environment variables.
One underused feature inside the Claude code MCP server config file is environment variable expansion. Instead of hardcoding API keys, you reference them as ${API_KEY} inside the config. Each developer sets that variable in their own environment, and the config file stays clean and safe to commit. You can even set fallback defaults with ${API_KEY:-fallback_value} for situations where a variable might not be set.
Claude Code will ask for approval before using a project-scoped server from .mcp.json. That’s intentional; it prevents automatically trusting a server that got added to the repo without your knowledge. If you need to reset those approval choices, the Claude MCP reset-project-choices command handles it.
[INTERNAL LINK: how to manage Claude Code settings and configuration files]
How to use claude code mcp add for common tools
Let me make this concrete. Here’s how I’d add a few of the most commonly used servers.
For GitHub, you connect over HTTP and then authenticate through the /mcp command inside Claude Code. Once connected, you can ask Claude Code to review pull requests, create issues, and list open PRs; all through natural language.
For Sentry, the same approach. Add the HTTP server, run /mcp to trigger OAuth authentication, and then start asking things like “what errors spiked in the last 24 hours” or “which deployment introduced this issue.” That’s a workflow that used to take five browser tabs.
For PostgreSQL, the stdio transport makes more sense since you’re connecting to a local or private database. You pass the connection string as an environment variable, provide the server name, and Claude Code starts the process as needed. Then you can run queries in plain English without leaving your terminal.
When you want to check what servers you currently have configured, claude mcp list shows them all. Claude MCP gets [name], which gives you the details for a specific server. And if something’s misbehaving or you want to clean up, Claude mcp remove [name] takes it out.
In an active Claude Code session, the /mcp command displays server status and handles OAuth flows for any remote service that requires them. I check that command first; whenever a connection seems off, it usually tells me immediately if a server failed to start or needs re-authentication.
One setting worth knowing: if you’re working with servers that return large outputs, the default token limit is 10,000 tokens per MCP response. You can raise that with the MAX_MCP_OUTPUT_TOKENS environment variable. For database-heavy work or detailed monitoring data, raising that limit prevents truncation mid-result.
Managing claude code mcp servers without the headaches
Once you have a few servers running, keeping them organized matters. The scope system does most of the work, but a few habits keep things clean.
First, name your servers clearly. GitHub, Sentry, and Stripe-prod are instantly understandable. server1 is not. You’re typing these names months later, so treat them like variable names.
Second, keep sensitive credentials out of .mcp.json entirely. Use environment variable expansion instead. If your API key ever rotates, you update one environment variable on each machine rather than editing the config file and re-committing.
Third, understand that Claude’s code for MCP configurations follows a precedence order. If a server exists at both local and project scope with the same name, local wins. That’s by design; personal configs can override shared ones. It’s useful when you want to test a modified server locally before pushing the change to the team.
Dynamic tool updates also work nicely once you’re past initial setup. When an MCP server updates its available tools, Claude Code automatically picks up the changes, without requiring you to disconnect and reconnect. That means a server maintainer can add new capabilities, and your Claude Code session reflects those capabilities in the next interaction.
[INTERNAL LINK: troubleshooting Claude Code connection and tool errors]
My honest take on claude code mcp after using it across several projects
The first time Claude’s code mcp clicked for me was when I connected a Sentry server to a production debug session. I asked Claude Code a question that normally required three browser tabs and a copy-paste chain. It answered immediately with a clean summary. That’s not something you forget quickly.
The learning curve isn’t steep, the Claude MCP add command covers most of what you need, and the scope system becomes intuitive after a project or two. What takes more time is knowing which servers to trust and how to structure your team’s .mcp.json for real shared use. Those aren’t hard problems; they just need a little deliberate thought.
If you’re starting fresh, I’d suggest adding one server first. GitHub or Sentry are good choices because both have clear, immediate value. Get comfortable with the /mcp command, verify the connection, and run a few tasks through it. Once that feels normal, adding more servers takes minutes, and the payoff stacks quickly.
The Claude code MCP ecosystem is still growing, and that’s the truth. More servers are being added regularly, transport standards are maturing, and teams are discovering new patterns every month. Getting comfortable with the basics now means you’re positioned to take advantage of whatever comes next without scrambling to catch up..
Frequently Asked Questions
What is an MCP server and do I need one to use Claude Code?
You don’t need an MCP server to use Claude Code it works perfectly fine on its own. MCP servers are optional extensions that give Claude access to external tools, APIs, and data sources.
Think of them as plugins that expand what Claude can do. Without MCP, it works with your local files and codebase. Once you connect an MCP server, it can go further to query databases, pull data from GitHub, check Sentry errors, and more. Whether you need one depends on your workflow. If you’re mostly working with local code, you can skip it entirely.
If you want Claude Code to interact with your tools without copy-pasting between systems, a Claude Code MCP server changes what’s possible pretty quickly.
Where does the claude code mcp config file get stored?
It depends on the scope you choose when adding the server. For project-scoped servers, the ones you’d share with a team, the config lives in a .mcp.json file at the root of your project directory, which you can commit to version control. For local and user-scoped servers, the configuration is stored in ~/.claude.json in your home directory. The distinction matters because .mcp.json is meant to be shared, while ~/.Claude.json stays private to your machine. If you’re setting up a Claude code MCP server config that your whole team will use, project scope with .mcp.json is the right call. For personal tools or sensitive credentials, stick with local scope.