MCP: Connecting Claude to the Outside World

📚 Series Navigation: The previous post 21 Security and Risk Boundaries helped you figure out "when to trust AI with your code and systems". This post shifts direction — connecting Claude to the outside world. By default, it can only touch your local files and command line; it cannot reach your database, Jira, or Figma. MCP is the unified interface that lets it connect to a bunch of external services all at once.

A quick pitfall first - when I installed my first MCP server, I spent almost an hour wrestling with terminal errors.

At the time, I wanted to connect a database server. I copied a command from a repository's README that looked something like this: claude mcp add db -- npx server --transport stdio. I hit enter, and it wouldn't connect. First I suspected the network, then I thought the package wasn't installed properly. I deleted and reinstalled it multiple times, npx downloaded the package over and over, progress bars flew back and forth — but it just wouldn't connect.

Later, checking the official documentation, I realized the parameter positions were wrong. The docs state clearly: all options (--transport, --env, --scope) must be placed "before" the server name, and everything after -- (double dash) is the command to start the server. In the command above, --transport stdio was placed after --, so it was treated as an argument passed to the server, which naturally wasn't recognized. Plus, stdio is the default transport, so you don't even need to write it — the correct syntax is simply claude mcp add db -- npx server, connecting instantly.

I mention this pitfall to save you that hour of frustration: MCP itself isn't difficult; the hard parts are all these details about "positions", "scopes", and "whether approval is needed". Today, we'll fill in these pitfalls one by one, and finally, guide you hands-on to get a real server running.

After reading this post, you will get:

• A one-sentence explanation of what MCP is and exactly which shortcoming of Claude it addresses
• When to use the three server formats (local stdio, remote HTTP, deprecated SSE), clarified in one table
• The correct syntax for the claude mcp add command, and the differences between local / project / user scopes
• How tools appear to Claude after adding a server, and whether the first invocation requires your approval (echoing the previous post on permissions and security)
• A practical, follow-along exercise with expected outputs: connecting and verifying the official documentation server in 5 minutes

---

01 Understand First: Which Shortcoming Does MCP Actually Address

Let's give the conclusion first: Claude Code is by default an assistant that "only works locally", and MCP is the gateway that unifies its connection to various external services.

Think back to what Claude has been doing in the previous twenty-one posts — reading your files, modifying your code, running your commands. It's all local stuff. No matter how smart it is, it can't touch that ticket on your company's Jira, can't connect to data in your production database, and can't see the mockups designers drew in Figma. It can't reach this information, so your only option is to copy, paste, and feed it manually.

Analogy: A docking station with a bunch of ports. Your laptop is getting thinner, and you might only have one or two Type-C ports on the body; HDMI, Ethernet, USB drives, and card readers can't be plugged in. What do you do? Connect a docking station — plug in one cable, and HDMI, network, USB, and power are all connected. MCP is to Claude what this docking station is: connect once, and a bunch of external service tools are laid out right in front of it.

The official definition for it is:

Claude Code can connect to hundreds of external tools and data sources through the Model Context Protocol (MCP) (an open standard for AI tool integration). MCP servers provide Claude Code with access to your tools, databases, and APIs.

There's a key phrase here: open standard. MCP (Model Context Protocol, an open specification that dictates "how AI calls external tools") is not a proprietary protocol Anthropic plays with behind closed doors, but a public standard. The benefit is "connect once, use anywhere" — an MCP server you write for a specific database can be used by Claude Code, and also by any other MCP-supported clients.

When should you think of using it? The official guidance provides a very straightforward rule of thumb:

Connect a server when you find yourself copying data from another tool (like an issue tracker or monitoring dashboard) into a chat.

Here are a few scenarios you'll likely encounter, to give you a feel for what it can do once connected:

• "Implement the feature described in JIRA ticket ENG-4521, then open a PR on GitHub" — it reads the ticket itself, without you having to relay it
• "Based on our PostgreSQL database, find the email addresses of the 10 users who used the new feature this month" — it queries the database directly, without you needing to export a CSV and paste it in
• "Update the email template according to the new design version on Figma" — it reads the design draft, without you having to take a screenshot to describe it

💡 One-sentence summary: Claude defaults to only touching local files and commands, and can't reach your databases, tickets, or design drafts; MCP is that unified external interface—connect it once, and a bunch of external service tools are laid out right in front of it.

---

02 Three Server Formats: Running Locally vs. Connecting to the Cloud

There's more than one type of MCP server. Understanding their differences helps you know how to adapt a command you've copied. The core is just one question: is this server running on your own machine, or is it hosted at some URL?

Analogy: Devices plugged into the docking station—some are right on the desk, others are on the other side of the wall. USB drives and card readers are local devices plugged directly into the dock, right at hand; the Ethernet cable connects to servers in a data center, far away. MCP servers fall into these two categories too — one runs as a local process on your machine, the other is remotely hosted and you connect to it.

The official docs offer several transports (i.e., how Claude Code and the server "communicate"), but you'll only need two for everyday use, plus one that has been phased out:

Format	Runs Where	How to Add	Best For
stdio (Local process)	On your own machine, launched as a child process	claude mcp add <name> -- <command>	Tools that need to read local files directly, control local browsers, or connect to local database sockets
HTTP (Remote hosting)	At a specific URL	claude mcp add --transport http <name> <url>	Cloud services (like Sentry, Notion, GitHub), officially recommended
SSE (Remote, deprecated)	At a specific URL	claude mcp add --transport sse <name> <url>	Only seen in legacy configurations, use HTTP if possible

Let's clarify a few common pitfalls for beginners:

stdio servers don't specify --transport. Because local processes use the default stdio transport, you don't need to explicitly designate it. Its essence lies in the command string following -- — that's the instruction for "how Claude Code should launch this server". Take the official Playwright example (a tool that lets Claude operate a browser):

claude mcp add playwright -- npx -y @playwright/mcp@latest

The npx -y @playwright/mcp@latest after the -- is the startup command, with -y telling npx not to prompt for confirmation and just install it. An stdio server is essentially "Claude launching a mini-app in the background for you", so it requires your machine to have the necessary environment (this Playwright server needs a newer Node environment, check their docs for the exact version).

HTTP is the primary choice for connecting to cloud services. In official words:

HTTP servers are the recommended option for connecting to remote MCP servers. This is the most widely supported transport for cloud services.

For tools like Sentry, Notion, and GitHub, you don't need to install anything locally; just provide a URL and it connects:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Just recognize SSE (Server-Sent Events), don't start using it. The official docs clearly mark it as "deprecated":

The SSE (Server-Sent Events) transport is deprecated. Please use HTTP servers where available.

You generally only see SSE when taking over someone else's old .mcp.json. For newly added servers, always use HTTP.

💡 One-sentence summary: Use stdio for local tools (startup command goes after --, no transport flag needed), use HTTP for cloud services (provide a URL, officially recommended), and SSE is deprecated—replace it if you see it.

---

03 How to Add a Server: Commands, Scopes, and That Pitfall Detail

Now that we understand the formats, let's look at how to actually add them. Two commands conquer all, the rest is all details.

Adding a remote HTTP server — use --transport http, give a name, give a URL:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Adding a local stdio server — skip the transport, put the startup command after --:

claude mcp add airtable -- npx -y airtable-mcp-server

Here's the pitfall we tripped on at the beginning. The official docs highlight it specifically in a Note box, and it's worth pasting on your forehead:

All options (--transport, --env, --scope, --header) must precede the server name. Then -- (double dash) separates the server name from the command and arguments passed to the MCP server.

To put it plainly: all of claude mcp add's own flags must go in front, and everything after -- is for the server. Off by one position, and the command won't be recognized.

Three Scopes: Where Can This Server Be Used

When adding a server, there's another unavoidable choice: is this server only for the current project, shared with the team, or for all your projects? This is what "scope" manages, specified with --scope.

Analogy: How a printer is shared in an office. Some printers only connect to your computer, and only you can print (local); some are connected to the department share and registered in the asset sheet, so the whole team can use it (project, shared via git); some are your own portable printers that you can carry to any desk or meeting room (user, cross-project). The three scopes correspond to these three levels of "where it sits, who can reach it".

Here are the differences between the three scopes provided by the official documentation:

Scope	Loaded in Which Projects	Shared with Team?	Where it is Stored
local (Default)	Only current project	No, private to you	~/.claude.json (under that project's entry)
project	Only current project	Yes, via version control	.mcp.json in project root
user	All your projects	No, private to you	~/.claude.json (top-level mcpServers)

How to choose? Just remember these three rules:

• Personal experiments, carrying credentials you don't want in version control → local (default, used if --scope is omitted)
• Want the whole team to use the same setup → project, it's written to .mcp.json, committed to git, and teammates get it when they pull
• Servers you personally use every day across projects → user, add it once, use it in all projects

# Available across all projects (user scope)
claude mcp add --scope user --transport http sentry https://mcp.sentry.dev/mcp

# Shared with the entire team (project scope, writes to .mcp.json)
claude mcp add --scope project --transport http github https://api.githubcopilot.com/mcp/

I've developed a habit through practice: for servers I use personally every day, like Sentry or GitHub, I strictly use user — I just add it once in the first project, and it's automatically there when I open a new project, saving me from redundant configuration. Initially, I used the default local for everything out of convenience, only to have to re-add it when I switched projects; after being annoyed a few times, I realized I should be using user. I only use project to write into .mcp.json when "this server is exclusive to this project, and collaborators need to use it too".

You Can Also Write .mcp.json Directly

For the project scope file, you can also write it manually. It's essentially just JSON, with different fields for HTTP and stdio servers:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

HTTP uses url, stdio uses command and args. Being checked into version control, it leaves the team with "configuration as code" — when someone clones the repo and starts Claude Code, it will read this configuration. Note an official tip: after modifying .mcp.json, you need to exit and restart the session for it to take effect, because Claude Code only reads it on startup.

💡 One-sentence summary: For HTTP, use --transport http and provide the URL; for stdio, use -- followed by the command, putting all flags before the name; remember the three scopes—use local for personal experiments, user for cross-project use, and project in .mcp.json for team sharing.

This diagram portrays the role of MCP as that middle "docking station": on the left are Claude Code's built-in local tools (reading/writing files, running commands), and on the right is the external world it normally cannot reach (GitHub, Jira, PostgreSQL, Figma, Sentry)—the MCP layer in the middle uses stdio and HTTP connections to wire them together, making the external service tools appear directly in front of Claude.

---

04 After Adding: How Tools Appear and Whether Invocation Requires Your Approval

Once the server is added, what happens next ties directly back to the permissions discussed in the previous post.

First, let's talk about how tools "appear". Every MCP server comes with a set of tools (for example, the GitHub server brings tools like "read PR" and "open issue"). Once added, these tools are registered to Claude, and it can call them just like its built-in tools. How do you confirm it connected and see what tools are available? Two commands:

# In the terminal: list all configured servers and their connection status
claude mcp list

# In the Claude session: view the status and tools of each server
/mcp

claude mcp list shows you the status markers for each server, and you need to know what they mean (as they directly answer "why isn't my server working?"):

Status	Meaning
✓ Connected	Connected and ready to use
! Needs authentication	Connected but requires login (OAuth or token); go to /mcp to authenticate
✗ Failed to connect / Connection error	Cannot connect (server unresponsive or command failed to run); check the command / URL
⏸ Pending approval	A project server from .mcp.json that hasn't been approved by you yet

That ⏸ Pending approval is the first place "whether it needs your approval" comes into play. The official design is very cautious:

For security reasons, Claude Code prompts for approval before using project-scoped servers from an .mcp.json file.

Why is this step necessary? Think about it: you clone someone else's repo, and the .mcp.json inside says "run a certain local server on startup". If it runs automatically without your consent, it essentially means someone else's repo silently launched a process on your machine. This approval barrier is there to prevent exactly that — echoing the security theme from the previous post: for things from unfamiliar sources, stop and wait for your nod first. (If you accidentally reject it, claude mcp reset-project-choices can reset it.)

The second approval happens the first time a tool is called. The official quickstart says:

The first time Claude calls the server, it asks for permission to use the new tool. Approve it to continue.

That is, adding a server ≠ Claude can use its tools freely. The first time it actually wants to call an MCP tool, it will still pause and ask you — this is the same permission mechanism as when it asks before modifying files or running commands in previous posts. It only proceeds if you approve.

There's also a considerate detail to help you "verify authenticity": when Claude calls an MCP tool, the tool invocation in the output is tagged with the server's name. This is your basis for confirming "this answer truly comes from the external service, it didn't just make it up". For instance, after connecting Sentry, seeing the sentry tag next to a tool call gives you peace of mind — it really did go and look up real error logs, not just the model hallucinating.

💡 One-sentence summary: Added MCP tools are registered to Claude, but there are two approval gates—the first load of a project .mcp.json server requires your approval, and the first invocation of a tool requires approval again; the server name tagged in the output is your proof to confirm "the answer really came from the outside".

---

05 The Trust Issue with Third-Party Servers: Don't Just Connect Anything

This section is the shortest, but the most crucial not to skip — it ties directly to the security boundaries from the previous post.

Let's put the official warning exactly as it is here, which appears in a red Warning box in the documentation:

Before connecting each server, please verify that you trust it. Servers that fetch external content may expose you to prompt injection risks.

Translated into plain English: MCP servers are code/services written by third parties, and Anthropic will not do security audits for you. Connectors in the official directory (Anthropic Directory) undergo basic review, but for servers outside the directory, you must judge their trustworthiness yourself.

Analogy: Installing a third-party dependency package into a production project. You wouldn't just npm install an unheard-of package with an unknown maintainer and let it run in your live code — you would first check who maintains it, how many people use it, and its reputation. An MCP server is essentially this kind of "third-party dependency": weigh its origins before installing, especially those that fetch external content (web pages, tickets, emails).

Why are servers that fetch external content riskier? Because they are hotbeds for prompt injection — a pitfall we specifically covered in the previous post. Simply put: the web page or ticket fetched by the server might hide a malicious instruction "written for the AI to read", and once Claude reads it in, it might be led astray. The "wilder" a server fetches, the greater this risk.

Here are a few practical rules of thumb for connecting servers that you can use:

Scenario	Connect or Not
Connectors reviewed in the official Anthropic Directory	✅ Prioritize choosing these
Official servers from major tech companies (GitHub, Sentry, Notion official)	✅ Relatively safe
Some random third-party server with few stars on GitHub	⚠️ Review the source code and think twice before connecting
Giving a server write access to your production database	❌ Keep it read-only if possible, don't give write access

The last rule is especially important. The official example of connecting a database deliberately uses a readonly account in the DSN — always use read-only credentials instead of writable ones when possible, this is the most practical move to keep risks at a minimum.

💡 One-sentence summary: MCP servers are third-party code, Anthropic doesn't audit them for you; verify trust before connecting, prioritize the official directory and major official servers, beware of prompt injections for servers fetching external content, and always use read-only accounts for databases first.

---

06 Hands-on: Connect a Real Server in 5 Minutes and Get It Running

Reading without practicing is just theory. Below, I'll guide you to connect the official documentation server — it's a hosted HTTP server that requires no login and no configuration, making it perfect for practice. It doesn't rely on any complex environment you might already have.

This server is a remotely hosted HTTP service, so adding it requires an internet connection; if you can't access code.claude.com domestically, turn on your "magic internet" (VPN/proxy) first and try again.

Step 1: Add the server (in the terminal, not in the claude session)

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

Expectation: Prints a confirmation line, similar to Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config. Seeing Added = configuration has been written (note it says local config, which means the default local scope, taking effect only in the current project).

Step 2: Check the connection status

claude mcp list

Expectation: claude-code-docs appears in the list, tagged with ✓ Connected. Seeing this green check = it really connected. If it shows ✗ Failed to connect, the network is likely blocked — follow the tip above to turn on your proxy and try again.

Step 3: Enter a session, call on it specifically to use this server

claude

Once inside, type (specifically calling the server to ensure it routes through MCP instead of using built-in web search for the same question):

Use the claude-code-docs server to check what the MCP_TIMEOUT environment variable is for

Expectation: Claude will stop and ask for your approval the first time it calls this server (this is the "first tool invocation requires approval" mentioned in section 04) — approve it. Then it will return the explanation for MCP_TIMEOUT (used to configure the startup timeout for MCP servers), and the tool invocation in the output will be tagged with claude-code-docs. Seeing this tag = the answer was truly looked up from the documentation server, not from the model's memory.

Step 4: Cleanup (Optional)

If you want to remove this server after practicing:

claude mcp remove claude-code-docs

Expectation: Prints a removal confirmation. Run claude mcp list again, and claude-code-docs is no longer in the list.

An official reminder worth noting: every connected server takes up a bit of the context window (its tool names and descriptions are loaded into each session). As discussed in the previous post, a crammed workbench makes it act dumb — promptly remove servers you don't use to free up that space.

By running through these four steps, you've personally navigated the complete loop of "add server → check status → approve invocation → remove". Connecting any server in the future is essentially this same process, just changing the name, URL, or command, and adding --scope or authentication as needed.

💡 One-sentence summary: Connecting the official documentation server is the safest way to practice — use add to attach, list to see the green check, explicitly call and approve it in the session, and remove to detach; personally completing this loop is more effective than memorizing ten commands.

---

07 Summary

In this post, we connected Claude to the outside world — moving from "only working locally" to "a single port connecting a bunch of services", all thanks to the MCP docking station.

Let's string the core points together for a review:

What You Need to Do	What to Use	Key Points
Understand what MCP does	An open integration standard	Claude normally can't reach external services; MCP connects them uniformly
Connect local tools	stdio	claude mcp add <name> -- <command>, don't write transport
Connect cloud services	HTTP	Give URL with --transport http, officially recommended
Decide where the server is used	Scope	Personal local, cross-project user, full team project (writes .mcp.json)
Confirm connection & available tools	claude mcp list / /mcp	Recognize states like ✓ Connected and ⏸ Pending approval
Control how Claude uses tools	Two approval gates	Initial project server load requires approval once, first tool call requires approval once

You should now be able to: understand which of Claude's shortcomings MCP addresses, distinguish how to add stdio vs. HTTP servers, use --scope to configure a server to the appropriate range, verify status with claude mcp list and /mcp after adding, know that there are two permission gates once tools appear to Claude, and understand to weigh trust before connecting third-party servers. This "external connection capability" is your key to upgrading Claude from a "local coding assistant" to something that "can directly manipulate your entire toolchain".

This one interface smooths out the pitfalls that caused an hour of frustration at the beginning — remember the rule "flags before the name, command after --", and you'll save yourself a lot of trouble.

---

Next up is 23 "Subagents" — MCP gives a single Claude more things it can do, but when there's too much work, one Claude can get overwhelmed and its context window will fill up. The next post teaches you a different approach: don't make one Claude shoulder everything, but instead hire a team of specialized subordinates with isolated contexts to divide the work — the main agent delegates, the subagents do their own things, and their respective contexts don't pollute each other. Think about it: if you can delegate "check logs", "write tests", and "run builds" to three undisturbed subordinates working concurrently, isn't that much more relaxing than having one Claude switch back and forth?

---

Recommended Reading

• GitHub Actions: Mention It in a PR and Let Claude Do the Work
• Voice Mode: Speak Your Prompts Instead of Typing Them
• Integrating Third-Party / Domestic Models