For Claude Code MCP, add a remote server with claude mcp add --transport http <name> <url>, then run claude mcp list and confirm its status. To keep its tools safe to call, use a whole-server permission only when every exposed tool is acceptable; otherwise, define an individual-tool boundary and review project-scoped configuration before a session can load it.
Set up Claude Code MCP
MCP is an open-source standard for connecting AI applications to external systems, according to the Model Context Protocol introduction. For a remote server, HTTP is the transport recommended in the Claude Code MCP documentation.
Start by deciding which server you trust, where its configuration should live, and which of its tools the agent needs. Those decisions matter because adding a server establishes a new route from Claude Code to an external system; it should not be treated as a harmless configuration change.
Add the remote server
The documented HTTP pattern is:
claude mcp add --transport http <name> <url>
The documentation gives this concrete Notion example:
claude mcp add --transport http notion https://mcp.notion.com/mcp
Both forms come from the Claude Code guide to connecting Claude Code to tools via MCP. Run the command in the intended project if you expect to keep the default local scope, because that scope is tied to the project where the server was added.
Before connecting any server, verify that you trust its operator and behavior. The Claude Code documentation specifically warns that servers fetching external content can expose users to prompt injection risk.
Choose the scope deliberately
Add commands write to local scope unless you include --scope project or --scope user. The practical difference is not merely where a command appears; it determines who receives the configuration and where Claude Code looks for it later.
- Local scope is the default. The server loads only in the project where you added it, remains private to you, and is stored in
~/.claude.jsonunder that project’s path. It does not appear in your other projects. - Project scope stores the configuration in
.mcp.jsonat the project root. This is the shareable option for a team, so changes to the file should receive the same review as other shared project configuration. - User scope is selected explicitly with
--scope user. Include that flag only when you intend the add command to write to user scope rather than the default local scope.
These scope behaviors are defined in the Claude Code MCP scope documentation. Do not switch to project scope merely to make configuration easier to find: the same change that makes the server available across a project also makes it part of a file other project participants may receive.
Preserve the stdio boundary
A local stdio server has a different launch boundary. The double dash -- separates Claude Code’s own options—such as --transport, --env, and --scope—from the command and arguments that start the server. Everything after -- is passed to the server untouched, as explained in the Claude Code MCP documentation.
That distinction prevents server arguments from being mistaken for Claude Code options, or Claude Code options from being sent to the server. Use the exact executable and arguments required by the selected server. The documentation does not prescribe one universal stdio executable, so check the server’s own launch instructions and Claude Code’s current MCP documentation when assembling the complete command.
Check it worked
Start with the connection check:
claude mcp list
The command displays a health status beside each server. The documented statuses include Connected, Needs authentication, and Failed to connect; see the Claude Code MCP connection check.
Treat those statuses as answers to a narrow question: can Claude Code see the configured server, and does its connection currently have the expected health? They do not prove that a particular tool call completed the intended work or that the server is appropriate for every permission you might grant.
If a project-scoped server comes from .mcp.json, Claude Code prompts for approval in an interactive session before using it. To reset those project approval choices, run:
claude mcp reset-project-choices
Both the interactive approval and reset command are documented under Claude Code MCP project servers.
Use that approval as a checkpoint rather than an inconvenience to bypass automatically. Before approving, check the server name, endpoint or launch command, scope, and the tools you expect it to expose. For a shared .mcp.json, also make sure the file’s current contents match the change you reviewed.
Claude Code also provides an /mcp panel. You can toggle a server off there to stop Claude Code connecting to it without deleting its configuration; the server remains listed as disabled. This gives you a reversible way to isolate a connection while preserving the setup for later review, according to the Claude Code MCP server controls.
Finally, exercise one narrowly chosen tool call in the relevant session and inspect the actual result. In our setup, our rule is that “done” means checked: an agent summary, exit code, or connection status is only a signal. The result has to be read back from where a user would see it before the workflow is complete.
Where it breaks
The most common failure is treating a successful connection as proof that every tool is safe. Anthropic’s guidance is to verify each server before connecting it and to account for prompt injection risk when a server fetches external content; the same warning applies to the Claude Code MCP security guidance. A healthy connection says nothing about whether the returned material is trustworthy or whether the server’s tool surface matches the task.
There is also a material difference between interactive and non-interactive sessions. In claude -p runs, Agent SDK sessions, and cloud sessions, Claude Code cannot show the project-server approval prompt, so project-scoped servers load without asking. The Claude Code MCP documentation describes that behavior directly. For these session types, review .mcp.json before execution; do not rely on an approval dialog that will not appear.
Permission rules need exact boundaries
Claude Code supports two MCP permission forms:
mcp__<server>
mcp__<server>__<tool>
The first matches all tools provided by that server. The second matches one tool on that server. The angle-bracket portions are placeholders for the actual server and tool names. Use the server-wide form only when every tool from that server belongs inside the boundary; otherwise, name the individual tools that are actually needed.
Rule evaluation is not based on choosing the narrowest-looking match first. The Claude Code permissions documentation defines the order as:
denyaskallow
The first match in that order determines the outcome, regardless of rule specificity. A broad deny therefore still wins over a narrower allow. Write and review the rules with that ordering in mind instead of assuming the most specific textual pattern automatically controls the result.
An unanchored allow glob such as mcp__* is skipped with a warning and does not auto-approve anything. It is not a usable substitute for enumerating a server boundary. To allow every tool from a named server, use the documented mcp__<server> form; to allow one tool, use mcp__<server>__<tool>.
Large tool output changes the result
Claude Code warns when MCP tool output exceeds 10,000 tokens and limits the output to 25,000 tokens by default. The limit can be raised with MAX_MCP_OUTPUT_TOKENS; the documentation gives this example:
MAX_MCP_OUTPUT_TOKENS=50000
The warning threshold remains fixed. These output limits are defined in the Claude Code MCP output-limit documentation.
Do not treat a long tool response as a complete result merely because the command returned successfully. If output reaches the limit, inspect what was actually returned before relying on it. Raising the cap can accommodate a larger response, but it does not turn an oversized response into a verified one. Check the downstream result instead.
Connection health is not task completion
Needs authentication identifies an authentication problem, while Failed to connect identifies a connection problem. The documentation does not say that one Claude Code command can repair or authenticate every MCP server, so use the selected server’s current instructions rather than inventing a universal flag.
Our own operating practices add two boundaries. Secrets appear only in the call that needs them; logs, reports, and screenshots carry key names rather than values. Outbound messages, payments, and final submissions to third parties wait for the human owner’s explicit approval. These are our operating rules, not Claude Code guarantees, but they provide a practical answer to the question left after configuration succeeds: which actions should an agent be allowed to finish without another approval step?
The safe sequence is therefore straightforward: add only a trusted server, choose the narrowest scope and permission boundary that meet the task, verify the connection, inspect the real tool result, and disable the server when it is not needed. That keeps MCP useful for execution without turning connection status into blanket authorization.