Hi, I'm Lena. MCP isn't a new concept anymore, but actually wiring up a server inside Claude Code without running into trouble is more nuanced than most people expect.
I've been using Claude Code with various MCP servers for my day-to-day development over the past few months — everything from GitHub to Sentry to custom internal database query tools. Honestly, the setup itself isn't hard — the hard part is figuring out what to trust, where to look when OAuth breaks, and how scope actually works. This article is a distilled collection of the gotchas I've hit and the official details I've tracked down, written for developers who are already using Claude Code and ready to connect MCP servers.
Prerequisites Before Connecting MCP Servers
Claude Code version and platform support
Start by checking your version. OAuth-related behaviors only stabilized after v2.1.64 — that's when authServerMetadataUrl support was introduced. Older versions will throw errors when authenticating with remote servers. There's also a known quirk on Windows: claude mcp add-json occasionally returns "Invalid input" when adding HTTP servers. The official MCP documentation recommends falling back to the claude mcp add --transport http format if you run into this.
What MCP can actually do inside Claude Code
MCP transforms Claude Code from a tool that can only read and write local files and run bash commands into an agent that can directly interact with external systems — pulling Jira tickets, creating GitHub PRs, querying Sentry for production errors, you name it. But here's a detail that often gets overlooked: MCP servers are completely isolated from each other. There's no passthrough — each layer is independent.
Tools, resources, and prompts
According to the MCP specification, a server can expose three types of capabilities: tools (executable actions), resources (readable data sources), and prompts (predefined interaction templates). The /mcp panel displays the tool count for each connected server, and it flags any server that declares the tools capability but doesn't actually expose any tools.
Step-by-Step: Adding Your First MCP Server
Adding a server via the CLI
Claude Code supports three transport types: HTTP (recommended for remote services), SSE (deprecated — avoid if possible), and stdio (local processes).
# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp
# Local stdio server
claude mcp add --transport stdio --env API_KEY=your_key myserver \
-- npx -y my-mcp-server
Here's the detail that trips people up: all options must come before the server name. The -- double dash separates Claude's flags from the arguments passed to the MCP server process. Get the order wrong and the command fails silently. I've been bitten by this more than once.
Adding via .mcp.json for team sharing
Use --scope project to write the configuration into a .mcp.json file that you can commit to version control. Never put actual tokens in this file — use environment variable references instead. Local-scoped configurations override project-scoped ones for same-named servers, which keeps credentials private.
Verifying the server is connected
Run /mcp inside Claude Code to check status and tool counts. HTTP/SSE servers automatically retry initial connections up to three times starting from v2.1.121, but authentication errors and 404s are not retried — those require a configuration change.
Approving tools on first use
The first time you invoke a tool from a new server, Claude Code will prompt for permission. This is trust verification by design. The Claude Code security documentation explicitly states that new MCP servers require user confirmation. You can approve once or choose "Always allow" to add it to your allowlist.
Authentication and OAuth Flow
Servers that require OAuth tokens
Most remote servers — GitHub, Slack, Notion, and similar services — require OAuth. Claude Code has built-in OAuth 2.1 support, and the flow is largely automatic: the server returns a 401, Claude Code discovers the OAuth metadata (first checking RFC 9728 Protected Resource Metadata, then falling back to RFC 8414), auto-registers as a client if Dynamic Client Registration is supported, opens a browser for authorization, and retrieves the token.
When a server doesn't support Dynamic Client Registration, you'll see an "Incompatible auth server" error. In that case, register an OAuth app through the server's developer portal, grab the client ID and secret, and add the server using --client-id and --client-secret. Some servers also require a fixed callback port — use --callback-port to match the redirect URI you registered.
Where credentials are stored and how to rotate them
Tokens are stored in your system's secure credential storage — macOS Keychain or an encrypted credentials file on other platforms. They are never stored in plaintext config files. To rotate credentials, open /mcp and re-authenticate for the relevant server. In SSH environments without a browser, Claude Code displays a "Paste code here" prompt so you can complete authorization on another machine and paste the result back.
Avoiding leaked tokens in shared configs
I'll be blunt here — I've seen more than one team push configs with hardcoded tokens to public repositories. Always use ${ENV_VAR} references for credentials. In enterprise environments, administrators can deploy a managed-mcp.json file with allowlist and denylist policies to control which servers can be used.
Security Boundaries to Check Before Trusting a Server
What an MCP server can read on your machine
A stdio-type server runs with your current user's permissions, which is something a lot of developers don't think carefully enough about. In theory, it can read your .env, SSH keys, and AWS credentials — anything your user account can access. Claude Code does have safeguards — write operations are restricted to the working directory, and network requests require approval. The Anthropic security engineering blog details the sandboxing mechanism, which includes both filesystem and network isolation working together. Their internal data shows that sandboxing reduces permission prompts by 84%, which is significant for daily workflow.
What it can execute or write
MCP tools can include arbitrary execution capabilities. A "run SQL" tool connected to a production database will genuinely execute queries against production data. This isn't hypothetical — I've seen setups where a single misconfigured tool had write access to a live customer database. Before connecting any server, you need to understand exactly which tools it exposes and what each one can actually do. Keep anything you're unsure about in ask mode rather than auto-approving.
Reviewing source and maintenance before approval
Before trusting a server, I typically do three things: review the source code (check the main entry file on GitHub to confirm what it actually does), assess the maintenance status (a package published 3 days ago versus one maintained for 2 years — completely different risk profiles), and check the permission declarations (per the MCP authorization specification, servers should declare their required scopes — watch for anything exceeding reasonable boundaries).
Common Issues and How to Fix Them
Server not appearing after add
The most common cause: wrong scope. A server added with --scope local in project A's directory won't be visible when you switch to project B. Use claude mcp list to confirm the scope, and switch to --scope user if you need it available everywhere. Also worth noting: workspace is a reserved name — using it will cause the server to be skipped with a warning.
Tool calls failing silently
First, check whether the output exceeds the 10,000 token default limit. Claude Code shows a warning when this happens, but it's easy to miss. Set MAX_MCP_OUTPUT_TOKENS=50000 to increase the ceiling. Another possibility is a disconnection — HTTP/SSE servers automatically reconnect with exponential backoff (up to 5 attempts), but stdio servers do not reconnect automatically.
Scope conflicts between local and project configs
When a same-named server exists in both local and project scope, local overrides project. This is by design, but if you don't know about it, you'll wonder why your .mcp.json changes aren't taking effect. Use claude mcp get <name> to see which configuration is actually active.
Permission prompts repeating every session
If you didn't select "Always allow," the approval won't persist. Use /permissions to manage your permanent allowlist. The Claude Code GitHub repository has documentation on PreToolUse hooks, which enable more granular automated approval logic.
Where Connection Stops Being Enough
MCP gives tools, but it does not preserve what worked
This is the limitation I feel most keenly in daily use. MCP solves the "connection" problem — it does not solve the "memory" problem. You might spend 20 minutes today getting a database-query-plus-report-generation workflow running perfectly, only to find that tomorrow's new session has lost all of that context. You'll need to re-explain which tables to query, what format to output in, and which edge cases to handle. The MCP protocol includes no session persistence mechanism. Every connection is stateless. That's not a bug — it's a design boundary.
Why teams still repeat fixes across sessions and machines
Developer A figures out the correct way to use a particular server, works through an edge case, and gets everything running smoothly. But that hard-won knowledge has nowhere to live. Developer B joins the project a week later and hits the exact same issues, spending the same time debugging the same problems. .mcp.json shares configuration — it doesn't share "how to actually use it" or "what broke last time and how we fixed it." CLAUDE.md files can partially mitigate this, but they're static and manually maintained. MCP does what it does very well, but for complex workflows, you'll eventually face the problem of lost context and repeated tribal knowledge.
FAQ
Is MCP the same as a plugin?
Not exactly. MCP is an open protocol standard that defines how AI applications communicate with external tools. Plugins are a higher-level concept in Claude Code that can include MCP server configurations along with other types of extensions. Anthropic's announcement page has the original MCP launch post.
Do I need an API key to use MCP servers?
It depends on the server. Local stdio servers typically don't require any authentication. Remote HTTP servers usually need credentials — either a Bearer token (passed via --header) or OAuth (handled automatically).
Can teammates see my MCP servers?
Only --scope project configurations are written to .mcp.json and visible to your team. Both local (the default) and user scopes are private.
What is the difference between local, project, and user scope?
local (default): available only to you in the current project directory. project: written to .mcp.json at the project root, shared with the entire team via version control. user: available to you across all projects on your machine. Note that in older versions, local was called "project" and user was called "global" — the naming has since been updated, so don't get confused by older blog posts or guides that use the old terminology.
Why does Claude Code keep asking permission for the same tool?
New sessions don't inherit temporary approvals by default. Use "Always allow" or /permissions to add tools to your permanent allowlist. In enterprise setups, deny rules in managed-settings.json override your local allow rules, which can also cause repeated rejections.
Previous Posts:
- Want a clearer mental model of MCP itself and why it’s becoming the standard layer for AI tool connections? Read: What Is MCP AI Tool Connection Standard
- If you're planning to actually use MCP inside Claude Code, this practical setup and extensions guide pairs naturally with the workflow discussed above: Claude Code MCP Setup Extensions Guide
- Curious which MCP servers are genuinely useful in day-to-day development rather than just demo-worthy? This real-world roundup is worth bookmarking: Best MCP Servers Real World Usefulness
- MCP handles connections, but Claude Skills handle reusable behavior layers — this developer reference explains that side of the stack in much more depth: Claude Code Skills Developer Reference
- The “connection vs memory” limitation mentioned in this article leads directly into local persistence and workflow continuity problems explored here: Claude Code Local Skills Memory Persistence




