← Claude Code, start to finish
Claude Code

MCP Deep Dive — Connecting Claude Code to Your Real Systems

31 Jul 2026·7 min read

Subagents were a big step. They let you hand off a slice of work to a fresh worker with its own context. But there is a wall that delegation alone never breaks: a subagent still only sees your code and your local machine. It cannot open your Jira board, read a Slack thread, or query your database. That gap is exactly where MCP comes in — the Model Context Protocol from the last post gives Claude Code access to your tools, databases, and APIs. This is the deeper cut, checked against the official docs.

Three transports, and when to use each

  • stdio is a local server that Claude Code starts as a subprocess on your machine. Use it for tools that need direct system access, like a browser, your filesystem, or a database socket.
  • HTTP is the recommended option for remote, hosted servers. It is the most widely supported transport for cloud services, and it supports OAuth sign-in.
  • SSE, short for Server-Sent Events, is the older remote transport. It is deprecated now, so reach for HTTP where it is available.

Adding a server

# Hosted HTTP server (remote service)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Local stdio server (subprocess on your machine)
claude mcp add playwright -- npx -y @playwright/mcp@latest

# Check the connection status
claude mcp list
A hosted server takes the transport flag and a URL. A local one has no transport flag, and everything after -- is the command that starts it.

For a server behind a login, like Sentry, Linear, or Notion, you add the URL the same way, then authenticate in the browser. After adding, claude mcp list shows the server as Needs authentication. Start a session, run /mcp, select the server, and choose Authenticate. Your browser opens the sign-in page, you approve, and the status changes to connected.

Config as code: commit your .mcp.json

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}
A project-scoped .mcp.json in the repo root. HTTP entries carry type and url; stdio entries carry command and args. Commit it and the whole team gets the same servers.

The first time Claude Code sees a project-scoped server it asks each person to approve it, so a repo you clone cannot launch processes on your machine without consent. That approval prompt is a feature, not a hurdle.

Scopes decide reach

  • local is the default. The server loads only in the current project and stays private to you, stored in your ~/.claude.json.
  • --scope user also stores the server in ~/.claude.json, but makes it available across all your projects, still private to you.
  • --scope project writes to .mcp.json in the project root and shares it with your team through git. When a server is defined in more than one place, Claude Code uses the highest-precedence source: local, then project, then user.

Managing servers is a small set of commands. claude mcp list shows every server and its status, claude mcp get name shows the detail and scope of one, claude mcp remove name deletes it, and inside a session /mcp is where you check status, authenticate, and reconnect a server that dropped.

Security firstThe docs are blunt about this: Verify you trust each server before connecting it. Servers that fetch external content can expose you to prompt injection risk. An MCP server can read your data and act on your systems, so a third-party server is only as safe as the party behind it. Add servers you trust, and keep credentials out of committed files.

Try it: share your servers as config-as-code

Let me walk you through the exact flow I use to share servers with a team. In the section above we committed a .mcp.json by hand. Here is the deeper, step-by-step version: add a server at project scope, read the file Claude Code writes, commit it to git, and watch what a teammate sees on first use. Every command and the file shape below are checked against the official docs.

  • Add the server at project scope. Run claude mcp add with --scope project. This does not touch your private local config; it writes to a shared .mcp.json in the project root instead.
  • Open the .mcp.json Claude Code just wrote. Each server sits under the mcpServers key: an http entry carries type and url, a stdio entry carries command and args.
  • Commit the .mcp.json to git and push it. The docs are clear that this file is designed to be checked into version control, so the whole team gets the same servers.
  • A teammate clones the repo and starts Claude Code. On first use they get an approval prompt for each project-scoped server, and once they approve, the server connects for them too.
# Add a hosted HTTP server at project scope
claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp

# Add a local stdio server at project scope
claude mcp add --scope project playwright -- npx -y @playwright/mcp@latest

# Confirm the servers are registered and check their status
claude mcp list
The --scope project flag is the whole trick. A hosted server takes --transport http and a URL; a local one has no transport flag, and everything after -- is the command that starts it.
{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}
The .mcp.json Claude Code writes at the project root. HTTP entries carry type and url; stdio entries carry command and args. This is the config-as-code the whole team shares.

Now commit it. git add .mcp.json, commit, and push, exactly like any other file in the repo. Keep secrets out of it — for a server behind a login you commit only the url, and each person signs in on their own machine. There is nothing private in this file, which is the point.

Here is what your teammate sees. The docs put it plainly: for security reasons, Claude Code prompts for approval before using project-scoped servers from .mcp.json files. So the first time Claude Code sees the shared server, it asks them to approve it, so a repo they clone cannot start processes on their machine without consent. In claude mcp list an unapproved server shows as Pending approval (run claude to approve). Once they approve, the servers connect and every teammate has the same tools available.

One extra beat for servers behind a login. Say you also add Sentry at project scope with claude mcp add --scope project --transport http sentry https://mcp.sentry.dev/mcp. After the approval, claude mcp list shows it as Needs authentication. Each person starts a session, runs /mcp, selects sentry, and chooses Authenticate; the browser opens the sign-in page, they approve, and the status changes to connected. The server is shared through git, but every person authenticates as themselves — which is exactly what you want.

Where it all pays off: with a Jira server and a GitHub server connected, you can say Add the feature described in Jira issue ENG-4521 and create a PR on GitHub. Claude reads the issue from Jira, implements the change in your code, and opens the pull request — no pasting, no tab-hopping. This deep dive was prompted by a sharp question from the community: the jump from subagents to connecting real systems deserved its own post. It did. If you have been meaning to try MCP, start small: connect one read-only server, commit a .mcp.json, and feel the difference when Claude stops asking you to paste things in. Next post: plugins, output styles, and scheduling jobs.

MCP Deep Dive — Connecting Claude Code to Your Real Systems · Ali Huzaifa