04-9 Cross-Tool Integration and MCP

What this unit solvesMCP (Model Context Protocol) is the standard protocol for connecting external tools and data sources to an agent. You will learn what integration problem MCP solves, how to configure and verify a server, how to evaluate a server by trust level and permission scope, and how it compares to CLI tools and built-ins for each scenario. The goal is a clear, actionable criterion for when to use MCP and when not to.

Learning objectives

Explain what MCP is, which integration problem it solves, and why a cross-tool protocol is needed.
Configure and verify a local MCP server (using Claude Code as the primary reference).
Evaluate whether to introduce a given MCP server based on trust source and permission scope.
Explain the trade-offs between MCP, CLI, and built-in tools, and know when to prefer CLI (see 04-10).
Identify the primary MCP attack surfaces and apply minimum-necessary protections (see 03-3).

1. What MCP is

MCP (Model Context Protocol) is an open standard proposed by Anthropic in 2024 that defines how external tools and data sources are called by an LLM. An MCP server exposes three interface types: tools (callable functions), resources (referenceable data), and prompts (executable command templates). Once an MCP client (such as Claude Code, Cursor, Claude Desktop, or Codex) connects, it mounts these interfaces into its own context so the model can call them exactly like built-in tools [1]. The concrete problem it solves: integration fragmentation. If every LLM tool (Claude Code, Cursor, Codex, Antigravity…) had to build its own interface for GitHub, Slack, and Postgres separately, the N x M development and maintenance cost would push integration behind a paywall. MCP compresses that to N+M: a server is written once and reused across multiple clients; a client with built-in MCP capability needs no per-service customization. Key concepts:

MCP server: a process or service that exposes tools, resources, and prompts. Can be a local stdio process (npx server-foo) or a remote HTTP / WebSocket service.
MCP client: the model-side caller. Claude Code has a built-in MCP client; once a server is attached, its tools are mounted under the mcp__<server>__<tool> namespace.
Transport: the protocol between client and server. Claude Code supports stdio (local process), http (including the streamable-http alias, the most widely supported cloud transport), sse (deprecated), and ws (WebSocket, for servers that need to push events) [1].

Division of responsibility: MCP vs. Skill vs. SubagentMCP is the interface for connecting external systems. A Skill is a container for wrapping procedures; a Subagent is an executor that isolates context. The three operate at different levels: MCP provides capability, Skill provides process, Subagent provides environment. One external system should be connected through exactly one mechanism — do not wrap MCP inside a Skill and then spin up a Subagent to run it on top.

Official security noticeAnthropic states explicitly in the MCP chapter: “Verify you trust each server before connecting it. Servers that fetch external content can expose you to prompt injection risk” [1]. This is not a formality. Strings returned by an MCP server land directly in the model’s context, making it a high-frequency entry point for prompt injection.

2. Connecting a server: configure, register, verify

Claude Code offers three installation paths (as of 2026-06, per the official MCP chapter [1]):

2.1 Via `claude mcp add` CLI (most common)

# 1. Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 2. With authentication header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# 3. Local stdio server
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

# 4. From JSON config
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

Option orderingAll options (--transport, --env, --scope, --header) must come before the server name; -- separates the server name from the server’s own command / args [1]. Mixing them causes Claude’s flags and the server’s flags to collide.

2.2 Three scopes

Where the config is stored and whether it is team-shared is controlled by --scope [1]:

Scope	Loaded for	Shared	Stored in
`local` (default)	Current project	No	`~/.claude.json` (under that project’s path)
`project`	Current project	Yes (committed to VCS)	`.mcp.json` in the project root
`user`	All your projects	No	`~/.claude.json`

Important security design: project-scope servers (from .mcp.json) are flagged as pending approval when Claude Code starts and require an interactive review before they activate [1]. This is the protection added after CVE-2025-59536: .mcp.json cannot silently auto-approve unknown servers without the user’s knowledge.

“local scope” and “local settings” are two different thingsMCP local scope is stored in ~/.claude.json; ordinary local settings live in .claude/settings.local.json. The names are similar but the layers are different [1].

2.3 Editing `.mcp.json` directly

For project scope or when you need environment variable expansion:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      },
      "timeout": 600000
    },
    "database-tools": {
      "command": "/path/to/server",
      "args": ["--config", "/path/to/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

Both ${VAR} and ${VAR:-default} expansion syntax are supported; an unset variable with no default causes Claude Code to fail when parsing the config [1]. timeout is the hard wall-clock limit per tool call for that server (milliseconds) and can be overridden with the MCP_TIMEOUT environment variable.

2.4 Verifying the connection

After installing, run:

claude mcp list          # list all servers and their status
claude mcp get github    # inspect a single server in detail

Inside Claude Code:

/mcp                      # open the MCP management interface; shows tool count and connection status per server

Verification SOP:

Confirm the server appears in /mcp

Run /mcp and confirm the target server shows as connected with the expected tool count.

Run a simple call

For example, call mcp__notion__search with a simple query and confirm the model can invoke it and receive a response.

Confirm the response format matches expectations

Check that the returned data structure matches the server’s documentation; rule out schema version mismatches.

Observe the OAuth flow on first call

HTTP servers typically require an initial OAuth authorization. Confirm the scope matches your actual needs — do not accept it wholesale.

Common configuration mistakes

Path does not exist: command is an absolute path but the file is not there; run which <command> first.
Wrong type name: the HTTP transport officially accepts both http and streamable-http (the MCP spec name); do not write https [1].
Environment variable not set: ${API_KEY} has no value; startup fails.
Multiple servers collide on the same port: two servers hard-coded to the same port; the second one to start will fail.

3. Choosing a server: trust, permissions, and official status

Before introducing an MCP server, work through these three questions:

3.1 Three trust tiers

Tier	Source	Handling
High	Servers bundled with the Anthropic-curated `claude-plugins-official` marketplace, or first-party releases from the tool vendor (GitHub, Notion, Atlassian, Stripe, etc.)	Still review `.mcp.json` content and server code
Medium	Well-known open-source repos with an issue tracker, releases, and active community maintenance	Run the additional `rg` supply-chain scan (see Section 5)
Low	Private URLs, forks that have not been updated in a long time, single-maintainer projects	Default: do not install; if you must, read the full source first

3.2 Permission scope

The env and args the server declares in .mcp.json hint at which resources it requires. Map that to “does this server actually need this?”:

A server that only runs grep does not need write access.
A server that only queries issues does not need outbound network access.
A server that simultaneously requires write + outbound network + ~/.ssh paths: maximum alertness.

The official code.claude.com/docs/en/permissions page provides three-tier allow / deny / ask rules for Bash, Edit, and Read; permission scoping for MCP servers uses mcp__<server>__* tool-level rules [2].

Permission review exampleA server’s .mcp.json config:

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

Review points: is this the official Slack server? The OAuth scope includes chat:write (can post messages) — does your workflow actually need the agent to post messages automatically? If not, remove chat:write from the scope and add it back only when the need arises [1]. oauth.scopes lets you narrow OAuth permissions to the minimum required (precise scope locking).

3.3 MCP servers bundled in plugins

A plugin can package MCP servers inside it [1]. Plugins in the claude-plugins-official and claude-community marketplaces automatically connect their bundled MCP servers when activated. Review these too: the mcpServers section in the plugin’s .mcp.json or plugin.json is where the server config lives.

Plugin MCP servers share the tool namespace with manually configured serversAfter activating a plugin, its MCP tools appear alongside manually configured MCP tools in the /mcp list. To distinguish by source, look at the plugin label in the /mcp interface [1].

4. Trade-offs against CLI and built-in tools

4.1 Decision criteria

Situation	Preferred choice
The operation has a complete CLI (`git`, `gh`, `docker`, `kubectl`, `psql`, etc.)	CLI (see 04-10 CLI-first)
The operation is already built into Claude.ai / Claude Code (Web search, Read, Edit)	Built-in
The service only exposes a REST / GraphQL API with no suitable CLI	MCP (wrap as a server) or WebFetch
The service has an official MCP server (GitHub, Notion, Atlassian, Stripe, etc.)	MCP (the most common right answer)
The same operation needs to run across multiple clients (Claude Code + Cursor + Codex)	MCP (the core value of a cross-tool standard)

4.2 Situations where MCP is the wrong tool

One-off commands: running gh pr list via the Bash tool is sufficient; there is no need to install the GitHub MCP server.
Heavy shell pipelines: multi-step pipelines like find | xargs grep | sed | jq are handled most directly in the shell; wrapping them as MCP requires splitting into multiple tool calls, each consuming context.
Operations requiring high auditability: CLI commands go into shell history; MCP calls require separate logging configuration.

4.3 Never mix CLI and MCP for the same operation

Mixing is a source of silent bugs: you run gh pr create in the shell while the agent simultaneously calls mcp__github__create_pull_request via MCP — both succeed, and the state is now inconsistent. Pick one path per operation; once you switch to a fallback, do not revert to mixing (see 04-10 for a full treatment).

5. Security boundaries

MCP is a high-leverage integration interface and a high-leverage attack surface. Cross-reference the supply-chain SOP in 03-3 Security, Privacy, and Supply-Chain Risk and 04-7 Plugins; this section covers only what is MCP-specific:

5.1 Attack surfaces

Attack surface	Description
`.mcp.json` brought in by a repo	Project-scope servers travel with `.mcp.json`; after cloning an unfamiliar repo, a server may attach automatically. Project scope requires user approval, but if the user clicks through without reading, a malicious server is already active
Tool return value injection	Strings returned by an external server land directly in context — a prompt injection path
`enableAllProjectMcpServers` setting	Enables all; reject by default
`headersHelper` arbitrary command execution	Introduced in v2.1.64+; still executes under project / local scope. Once the project-scope trust dialog is confirmed, it runs [1]
Overly broad `oauth.scopes`	Server requests more scope than its actual function requires

5.2 Minimum necessary protections

# 1. Pre-install scan: suspicious outbound commands
rg -n 'curl|wget|nc|ssh|ANTHROPIC_BASE_URL|enableAllProjectMcpServers' ~/.claude/ .mcp.json

# 2. Hidden Unicode and bidi overrides
rg -nP '[\x{200B}-\x{200D}\x{202A}-\x{202E}]' ~/.claude/ .mcp.json

# 3. HTML comments, script tags, base64
rg -n '<!--|<script|data:text/html|base64,' ~/.claude/ .mcp.json

Combined with the general SOP from 03-3: block sensitive paths (~/.ssh, ~/.aws, **/.env*) in permissions.deny; log MCP tool calls; review the active server list once per quarter.

5.3 Tool search and context control

Claude Code enables MCP tool search by default: MCP tools are not fully loaded into context at session start but are dynamically discovered by Claude via ToolSearch [1]. This substantially reduces context cost for multi-server setups, but it is not a security mechanism. Connected servers can still be called when the task is relevant to them. For particularly sensitive servers, combine alwaysLoad: false (the default) with a mcp__<server>__* rule in permissions.deny.

6. Tool comparison

Naming and boundaries

Claude Code has a built-in MCP client; no plugin is required to use MCP servers.
OpenAI, Antigravity, GitHub Copilot, and Cursor vary in how deeply and on what timeline they support MCP; check each vendor’s current official documentation before adopting.
SSE transport is marked deprecated in the official documentation; use http for new configurations [1].

Hands-on exercises

30-minute practice

Get a server running (15 minutes): install claude mcp add --transport http notion https://mcp.notion.com/mcp (or choose a service you already have an account for, such as Sentry or GitHub). Confirm the status in Claude Code’s /mcp interface, then run one simple call to verify the connection.
Write a project-scope config (10 minutes): take an operation you currently perform via MCP and move it to .mcp.json under project scope. On the next Claude Code startup, observe the user-approval dialog and decide whether to approve or reject.
Security scan (5 minutes): run the three rg scans from this section against ~/.claude.json and .mcp.json, record every hit, and review each manually.

Common pitfalls

Anti-pattern list

Trusting a repo’s .mcp.json without reviewing it: this is equivalent to letting external code decide your agent’s tool set. The first thing to do after cloning an unfamiliar repo: open .mcp.json and read it.
Granting MCP servers overly broad permissions (write + outbound network + ~/.ssh path), far beyond what their actual function requires. Start with the narrowest scope; add more only when needed.
Mixing CLI and MCP for the same operation: produces results spliced from two sources with inconsistent state. One operation, one path (see 04-10).
Installing servers and never reviewing them: /mcp lists a dozen entries and you have forgotten why several were added. Audit once per quarter and remove unused servers with mcp remove.
Accepting every OAuth scope the server requests. Default deny; add only the scopes the feature actually needs.
Treating MCP as a universal solution: MCP solves “integrating services with no suitable CLI.” When a CLI exists, prefer it (see 04-10).

Self-check

The bar for passing this unit

Can you state the difference between MCP’s three scopes in under a minute, and identify which one triggers user approval?
Can you list at least three questions to ask when deciding whether to install a given MCP server?
For the MCP server you currently use (or are considering adding): can you state its trust tier, its declared permission scope, and whether you have verified it only uses those permissions?
Can you run all three rg supply-chain scans before installing a new MCP server?

Sources and further reading

Factual claims are grounded in official documentation; fast-changing items are annotated as of 2026-05.

[1] Anthropic, “Connect Claude Code to tools via MCP,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/mcp (as of 2026-06; covers four transport types, three scopes, OAuth, headersHelper, tool search, streamable-http alias, security notice, and the claude.ai/directory official server directory)
[2] Anthropic, “Configure permissions,” code.claude.com, 2026. [Online]. Available: https://code.claude.com/docs/en/permissions (as of 2026-06; MCP tool-level mcp__server__* allow / deny rules and how they compose with Bash / Edit rules)
[3] Model Context Protocol, “MCP specification,” modelcontextprotocol.io, 2026. [Online]. Available: https://modelcontextprotocol.io (as of 2026-06; official specification home)
[4] Snyk, “ToxicSkills: 2026 Report on Malicious Skills in the Wild,” snyk.io, 2026. [Online]. Available: https://snyk.io (as of 2026-06; supply-chain risk statistics for Skills / MCP servers)
[5] OpenAI, “Model Context Protocol,” developers.openai.com, 2026. [Online]. Available: https://developers.openai.com/codex/mcp (as of 2026-06; Codex CLI MCP config.toml location, stdio and Streamable HTTP transport, OAuth and bearer token authentication)
[6] Google, “MCP servers with Gemini CLI,” google-gemini.github.io, 2026. [Online]. Available: https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html (as of 2026-06; settings.json path and mcpServers section, stdio / SSE / HTTP streaming transports)
[7] GitHub Docs, “Adding MCP servers for GitHub Copilot CLI,” docs.github.com, 2026. [Online]. Available: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers (as of 2026-06; ~/.copilot/mcp-config.json, stdio / HTTP / SSE transport, GitHub MCP Registry)
[8] Cursor, “MCP,” cursor.com, 2026. [Online]. Available: https://cursor.com/docs/cli/mcp (as of 2026-06; .cursor/mcp.json and ~/.cursor/mcp.json locations, stdio and Streamable HTTP transport)

Security: 03-3 Security, Privacy, and Supply-Chain Risk.
CLI-first principles: 04-10 CLI-first vs. MCP.
Built-in tool inventory: 04-8 Vendor Built-in Tools.
MCP servers bundled in plugins: 04-7 Plugins.
Preloading servers via mcpServers in a Subagent: 04-5 Subagents.
Enforcement via hooks: 04-6 Hooks.

Overview

Part I Foundations

Part II Configuration

Part III Judgment

Part IV Customization

Part V Case Studies

Appendix

04-9 Cross-Tool Integration and MCP

Learning objectives

1. What MCP is

2. Connecting a server: configure, register, verify

2.1 Via `claude mcp add` CLI (most common)

2.2 Three scopes

2.3 Editing `.mcp.json` directly

2.4 Verifying the connection

3. Choosing a server: trust, permissions, and official status

3.1 Three trust tiers

3.2 Permission scope

3.3 MCP servers bundled in plugins

4. Trade-offs against CLI and built-in tools

4.1 Decision criteria

4.2 Situations where MCP is the wrong tool

4.3 Never mix CLI and MCP for the same operation

5. Security boundaries

5.1 Attack surfaces

5.2 Minimum necessary protections

5.3 Tool search and context control

6. Tool comparison

Hands-on exercises

Common pitfalls

Self-check

Sources and further reading

​Learning objectives

​1. What MCP is

​2. Connecting a server: configure, register, verify

​2.1 Via claude mcp add CLI (most common)

​2.2 Three scopes

​2.3 Editing .mcp.json directly

​2.4 Verifying the connection

​3. Choosing a server: trust, permissions, and official status

​3.1 Three trust tiers

​3.2 Permission scope

​3.3 MCP servers bundled in plugins

​4. Trade-offs against CLI and built-in tools

​4.1 Decision criteria

​4.2 Situations where MCP is the wrong tool

​4.3 Never mix CLI and MCP for the same operation

​5. Security boundaries

​5.1 Attack surfaces

​5.2 Minimum necessary protections

​5.3 Tool search and context control

​6. Tool comparison

​Hands-on exercises

​Common pitfalls

​Self-check

​Sources and further reading

Learning objectives

1. What MCP is

2. Connecting a server: configure, register, verify

2.1 Via `claude mcp add` CLI (most common)

2.2 Three scopes

2.3 Editing `.mcp.json` directly

2.4 Verifying the connection

3. Choosing a server: trust, permissions, and official status

3.1 Three trust tiers

3.2 Permission scope

3.3 MCP servers bundled in plugins

4. Trade-offs against CLI and built-in tools

4.1 Decision criteria

4.2 Situations where MCP is the wrong tool

4.3 Never mix CLI and MCP for the same operation

5. Security boundaries

5.1 Attack surfaces

5.2 Minimum necessary protections

5.3 Tool search and context control

6. Tool comparison

Hands-on exercises

Common pitfalls

Self-check

Sources and further reading