MCP Server Integration

Official Exam Guide Objectives

Task 2.4: Integrate MCP servers into Claude Code and agent workflows.

Knowledge of

• MCP server scoping: project-level (.mcp.json) for shared team tooling vs user-level (~/.claude.json) for personal/experimental servers
• Environment variable expansion in .mcp.json (e.g., ${GITHUB_TOKEN}) for credential management without committing secrets
• That tools from all configured MCP servers are discovered at connection time and available simultaneously to the agent
• MCP resources as a mechanism for exposing content catalogs (e.g., issue summaries, documentation hierarchies, database schemas) to reduce exploratory tool calls

Skills in

• Configuring shared MCP servers in project-scoped .mcp.json with environment variable expansion for authentication tokens
• Configuring personal/experimental MCP servers in user-scoped ~/.claude.json
• Enhancing MCP tool descriptions to explain capabilities and outputs in detail, preventing the agent from preferring built-in tools (like Grep) over more capable MCP tools
• Choosing existing community MCP servers over custom implementations for standard integrations (e.g., Jira), reserving custom servers for team-specific workflows
• Exposing content catalogs as MCP resources to give agents visibility into available data without requiring exploratory tool calls

What You Need to Know

MCP (Model Context Protocol) servers are how Claude reaches systems it does not otherwise know about — databases, APIs, development tooling, issue trackers. Where the configuration lives decides whether a team shares one toolset or each developer quietly assembles their own.

The Scoping Hierarchy

Two levels exist, and most setup problems trace back to something sitting at the wrong one.

Project-level: .mcp.json Sits at the repository root and is committed, so it arrives with every clone and pull. This is where anything the team depends on belongs — the Jira connection, the GitHub tooling, the connectors to your own services.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "jira": {
      "command": "npx",
      "args": ["-y", "@community/mcp-server-jira"],
      "env": {
        "JIRA_URL": "${JIRA_URL}",
        "JIRA_TOKEN": "${JIRA_TOKEN}"
      }
    }
  }
}

User-level: ~/.claude.json Sits in your home directory. Personal, uncommitted, invisible to everyone else. Right for something experimental, a private integration, or a server you are trying out before suggesting the team adopt it.

Key principle: everything configured at either level is discovered when the connection is made, and all of it is available at once. Nothing has to be switched on — a server that is configured and reachable contributes its tools to the toolkit, which is also why an unnoticed user-level server can explain why one developer's agent behaves differently from everybody else's.

Environment Variable Expansion

.mcp.json expands ${VARIABLE_NAME}, and that is what makes it safe to commit a file describing servers that need credentials.

{
  "env": {
    "GITHUB_TOKEN": "${GITHUB_TOKEN}",
    "DATABASE_URL": "${DATABASE_URL}"
  }
}

What is committed is the variable name; the value stays wherever each developer keeps it — shell profile, .env, a secrets manager. Which gives you:

• The configuration file is safe to commit to version control
• Each developer authenticates with their own credentials
• Token rotation does not require config file changes
• No secrets leak through repository history

The third and fourth points are worth pausing on together: because the file never held the secret, rotating a token touches nothing in the repository, and there is no historical commit holding an old one either.

MCP Resources

Resources publish a catalogue of what exists, so an agent can find out without calling tools to go looking.

Worth publishing this way:

• Issue summaries — the open Jira tickets, with their titles and current status
• Documentation hierarchies — the contents page for whatever internal docs exist
• Database schemas — which tables exist, the types of their columns, how they relate

The saving is in calls never made. Lacking a schema resource, an agent orients itself by calling list_tables, then describe_table once per table — a sequence that produces no work, only the knowledge of what it could work on. Publish the schema and that knowledge is simply present.

Resources show agents what data is available. Tools let them act on it.

The Build-vs-Use Decision

It arrives constantly, in items and in real work: the team needs to talk to an external system, so does somebody write an MCP server or adopt an existing one?

Use community servers for standard integrations:

• Jira, GitHub, Slack, Linear and Notion all have community servers under active maintenance
• The ordinary cases are covered, exercised by more users than your team has, and kept current by someone else
• Adopting one costs an afternoon; owning one costs indefinitely

Build custom servers only when:

• The workflow is particular to your team and no general server expresses it
• Business rules need to live in the tool layer itself rather than in the prompt
• The system is proprietary, so no community server exists or could

The pragmatic answer is the one that scores. Where the integration is a standard one, evaluating what already exists comes first — and building is correct only where the scenario states a requirement no community server could meet, usually something proprietary or a workflow particular to that team.

Enhancing MCP Tool Descriptions

A subtler failure: an MCP tool with a thin description loses out to a built-in one even where it would do the job better. The built-ins arrive described in detail, so on a sparse comparison the model prefers what it understands.

The fix: enhance your MCP tool descriptions to explain capabilities and outputs in detail. Instead of:

search_codebase: "Search the code"

Write:

search_codebase: "Semantic search over the whole repository,
indexed by AST rather than by line. Matches functions, classes
and methods, returning each with its file path, line numbers and
the code around it. Because it matches on intent rather than on
exact strings, it finds code that grep would miss when you know
what something does but not how it is spelled. Prefer this to
Grep whenever the search is by behaviour rather than by text."

Note what the longer version supplies: what the tool does, what comes back, and an explicit comparison against the built-in it is competing with. That last part is what settles the choice, because the model now has grounds to prefer it rather than merely permission to.

Deep Dive

claude mcp add — the two command shapes

Claude Code's CLI adds servers with one command, in two shapes depending on transport. For a remote HTTP server (the recommended option for remote servers): claude mcp add --transport http <name> <url>. For a local stdio server, a -- separator is required: claude mcp add [options] <name> -- <command> [args...]. Everything after -- is passed to the server process untouched — it separates Claude's own flags (--transport, --env, --scope) from the command that launches the server. A server can also be added directly from a JSON blob with claude mcp add-json <name> '<json>'.

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

# Local stdio server — note the -- separator
claude mcp add --scope project github -- npx -y @modelcontextprotocol/server-github

Sourcecode.claude.com › mcpfetched 2026-07-30

Three scopes, not two — and where each one actually lives on disk

The -s/--scope flag accepts local (default; older Claude Code versions called this scope project), project (shared via .mcp.json), or user (older versions called this global). A local-scoped server loads only in the project where you added it and stays private to you — a different mechanism from a project-scoped server, even though both can feel "project-specific" at a glance. Note also: MCP local scope (~/.claude.json) is a different thing entirely from general local settings (.claude/settings.local.json, in the project directory) — don't conflate the two on the exam.

Sourcecode.claude.com › mcpfetched 2026-07-30

Scope precedence: local beats project beats user, no merging

When the same server name is configured at more than one scope, Claude Code does not merge the definitions — it "connects to it once, using the definition from the highest-precedence source. The entire server entry from that source is used; fields are not merged across scopes." The precedence order is: 1. Local scope → 2. Project scope → 3. User scope → 4. Plugin-provided servers → 5. claude.ai connectors. A personal local override therefore silently wins over the team's .mcp.json entry of the same name — useful for testing a fork of a server, but a source of "why isn't my teammate's config taking effect" confusion if undocumented.

Sourcecode.claude.com › mcpfetched 2026-07-30

Environment variable expansion: ${VAR} and ${VAR:-default}

.mcp.json supports two expansion forms: ${VAR} expands to the value of environment variable VAR; ${VAR:-default} expands to VAR if set, otherwise falls back to default. Expansion works in five fields of a server entry: command (the executable path), args, env, url (for HTTP servers), and headers (for HTTP authentication).

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "${INTERNAL_API_URL:-https://api.internal.example.com}",
      "headers": { "Authorization": "Bearer ${API_TOKEN}" }
    }
  }
}

Sourcecode.claude.com › mcpfetched 2026-07-30

Transports: stdio, Streamable HTTP, and deprecated SSE

The MCP specification defines two standard transports — stdio and Streamable HTTP — and clients SHOULD support stdio whenever possible. In stdio, the client launches the server as a subprocess and exchanges JSON-RPC over stdin/stdout. Streamable HTTP is for servers running as independent processes serving multiple clients, over HTTP POST/GET, optionally using SSE to stream multiple server messages — it replaces the older HTTP+SSE transport from protocol version 2024-11-05. In Claude Code specifically, the standalone SSE transport is deprecated; use HTTP servers where available, though --transport sse still exists for services that only expose SSE. In .mcp.json (and ~/.claude.json/add-json), the type field accepts streamable-http as an alias for http, so configs copied straight from third-party server documentation work unmodified. The Agent SDK docs give a simple heuristic for choosing: a command to run means stdio; a URL means HTTP or SSE; tools built in your own code use an SDK MCP server.

Sourcesmodelcontextprotocol.io › transportscode.claude.com › mcpcode.claude.com › mcpfetched 2026-07-30

Management, approval, and remote authentication

Configured servers are managed with claude mcp list, claude mcp get <name>, claude mcp remove <name>, and — inside a running session — /mcp to check server status. For security, Claude Code prompts for approval before using project-scoped servers from .mcp.json; reset those approval choices with claude mcp reset-project-choices. For remote servers requiring authentication, Claude Code supports OAuth 2.0: authenticate via /mcp (or claude mcp login <name>), and tokens are stored securely and refreshed automatically. Claude Code can also run in the other direction — claude mcp serve starts Claude itself as a stdio MCP server exposing its own tools to other MCP clients, which then become responsible for their own per-call user confirmation.

Sourcecode.claude.com › mcpfetched 2026-07-30

MCP resources and prompts are addressable, not just tool-adjacent

Resources aren't only conceptual "content catalogues" — they have concrete addressing syntax in Claude Code. Reference one with an @-mention: @server:protocol://resource/path; the referenced resource is fetched and attached automatically. Prompts exposed by a connected server become slash commands with the format /mcp__servername__promptname, and the prompt's result is injected directly into the conversation. Watch your MCP tool output size too: Claude Code warns when a tool's output exceeds 10,000 tokens and caps output at 25,000 tokens by default (raise the ceiling with MAX_MCP_OUTPUT_TOKENS) — a database-schema resource sidesteps this entirely for exploratory reads, since resources aren't subject to the same per-call output ceiling as a tool response.

Sourcecode.claude.com › mcpfetched 2026-07-30

Quick Reference

Exam Traps

Practice Scenario

Build Exercise

Configure MCP Servers with Scoping and Environment Variables

Difficulty: Beginner (1/4)

30 minutes

1. Create a .mcp.json file in your project root configuring a community MCP server (e.g. GitHub) with command and args

Why: Project-level .mcp.json is version-controlled and shared with every team member who clones the repository. The exam tests whether you know that team-wide servers belong here, not in ~/.claude.json. Using community servers for standard integrations is always the correct first choice.

You should see: A .mcp.json file at the project root containing an mcpServers object with at least one server entry specifying command (e.g. npx) and args (e.g. -y @modelcontextprotocol/server-github).

2. Use ${GITHUB_TOKEN} environment variable expansion for authentication credentials

Why: Committing credentials directly in .mcp.json is a security risk the exam penalises. The ${VARIABLE_NAME} syntax lets the configuration file reference environment variables without containing the actual values, keeping secrets out of repository history.

You should see: The env section of your server configuration contains ${GITHUB_TOKEN} (not an actual token value). Running git diff confirms no secrets are staged for commit. Each developer sets their own token locally.

3. Add a personal or experimental MCP server to ~/.claude.json for user-level configuration

Why: User-level configuration in ~/.claude.json is personal, not version-controlled, and not shared with teammates. The exam tests whether you know the scoping hierarchy: .mcp.json for team servers, ~/.claude.json for personal or experimental servers.

You should see: A ~/.claude.json file with an mcpServers entry for a personal server (e.g. an experimental integration you are testing). This file is NOT in your project repository and NOT in version control.

4. Expose a content catalogue (e.g. a documentation hierarchy or database schema) as an MCP resource

Why: MCP resources give agents visibility into available data without requiring exploratory tool calls. Without resources, an agent might call list_tables then describe_table for every table, wasting multiple tool calls. A schema resource makes that information available immediately.

You should see: An MCP resource definition that exposes structured data (e.g. a list of database tables with column types, or a documentation table of contents) accessible at a URI like db://schema/main. The resource should have a name, description, and mimeType.

5. Enhance the tool descriptions for your configured MCP server to explain capabilities and outputs in detail, preventing the agent from preferring built-in tools

Why: When an MCP tool has a sparse description, the agent prefers built-in tools like Grep because their descriptions are richer and more detailed. The exam tests whether you know that enhanced MCP descriptions are required to compete with built-in tools for selection priority.

You should see: Tool descriptions that are 3-5 sentences long, explaining what the tool does, what it returns, when to use it, and how it compares to built-in alternatives. For example, a search_codebase tool description that explicitly states it is more accurate than Grep for semantic searches.

Sources

• Claude Certified Architect Foundations Exam Guide — Domain 2, Task Statement 2.4 — Anthropic
• MCP Server Configuration — Claude Code Documentation — Anthropic
• Model Context Protocol — Resources — Model Context Protocol
• MCP Specification — Transports (2025-06-18) — Model Context Protocol
• Agent SDK — MCP — Anthropic

Appendix A — Build Exercise Step Hints

Progressive hints revealed by the "Stuck? Get a nudge" control on each step.

Step 1. Create a .mcp.json file in your project root configuring a community MCP server (e.g. GitHub) with command and args

Why: Project-level .mcp.json is version-controlled and shared with every team member who clones the repository. The exam tests whether you know that team-wide servers belong here, not in ~/.claude.json. Using community servers for standard integrations is always the correct first choice.

You should see: A .mcp.json file at the project root containing an mcpServers object with at least one server entry specifying command (e.g. npx) and args (e.g. -y @modelcontextprotocol/server-github).

Create .mcp.json with this content:
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Step 2. Use ${GITHUB_TOKEN} environment variable expansion for authentication credentials

Why: Committing credentials directly in .mcp.json is a security risk the exam penalises. The ${VARIABLE_NAME} syntax lets the configuration file reference environment variables without containing the actual values, keeping secrets out of repository history.

You should see: The env section of your server configuration contains ${GITHUB_TOKEN} (not an actual token value). Running git diff confirms no secrets are staged for commit. Each developer sets their own token locally.

# In your shell profile (~/.zshrc or ~/.bashrc):
export GITHUB_TOKEN=ghp_your_actual_token_here

# Verify the .mcp.json contains only variable references:
# "GITHUB_TOKEN": "${GITHUB_TOKEN}"  <-- correct
# "GITHUB_TOKEN": "ghp_abc123"       <-- WRONG, this is a leaked secret

Step 3. Add a personal or experimental MCP server to ~/.claude.json for user-level configuration

Why: User-level configuration in ~/.claude.json is personal, not version-controlled, and not shared with teammates. The exam tests whether you know the scoping hierarchy: .mcp.json for team servers, ~/.claude.json for personal or experimental servers.

You should see: A ~/.claude.json file with an mcpServers entry for a personal server (e.g. an experimental integration you are testing). This file is NOT in your project repository and NOT in version control.

# ~/.claude.json
{
  "mcpServers": {
    "experimental-search": {
      "command": "node",
      "args": ["/path/to/my/experimental-search-server.js"],
      "env": {
        "API_KEY": "${EXPERIMENTAL_API_KEY}"
      }
    }
  }
}

Step 4. Expose a content catalogue (e.g. a documentation hierarchy or database schema) as an MCP resource

Why: MCP resources give agents visibility into available data without requiring exploratory tool calls. Without resources, an agent might call list_tables then describe_table for every table, wasting multiple tool calls. A schema resource makes that information available immediately.

You should see: An MCP resource definition that exposes structured data (e.g. a list of database tables with column types, or a documentation table of contents) accessible at a URI like db://schema/main. The resource should have a name, description, and mimeType.

import { McpServer } from "@modelcontextprotocol/server";

const server = new McpServer({ name: "db-tools", version: "1.0.0" });

server.registerResource(
  "db-schema",
  "db://schema/main",
  {
    title: "Database schema",
    description: "Database schema with all tables, columns, and types",
    mimeType: "application/json",
  },
  async uri => ({
    contents: [
      {
        uri: uri.href,
        mimeType: "application/json",
        text: JSON.stringify({
          tables: [
            { name: "customers", columns: ["id", "email", "name", "tier"] },
            { name: "orders", columns: ["id", "customer_id", "status", "total"] },
          ],
        }),
      },
    ],
  })
);

import json

from mcp.server import MCPServer

mcp = MCPServer("db-tools")


@mcp.resource("db://schema/main", mime_type="application/json")
def db_schema() -> str:
    """Database schema with all tables, columns, and types"""
    return json.dumps(
        {
            "tables": [
                {"name": "customers", "columns": ["id", "email", "name", "tier"]},
                {"name": "orders", "columns": ["id", "customer_id", "status", "total"]},
            ]
        }
    )

Step 5. Enhance the tool descriptions for your configured MCP server to explain capabilities and outputs in detail, preventing the agent from preferring built-in tools

Why: When an MCP tool has a sparse description, the agent prefers built-in tools like Grep because their descriptions are richer and more detailed. The exam tests whether you know that enhanced MCP descriptions are required to compete with built-in tools for selection priority.

You should see: Tool descriptions that are 3-5 sentences long, explaining what the tool does, what it returns, when to use it, and how it compares to built-in alternatives. For example, a search_codebase tool description that explicitly states it is more accurate than Grep for semantic searches.

// Before (sparse — agent will prefer Grep):
// search_codebase: "Searches code"

// After (enhanced — agent can make an informed choice):
server.registerTool(
  "search_codebase",
  {
    description:
      "Performs semantic code search across the entire repository using AST-aware indexing. " +
      "Returns matching functions, classes, and methods with full context including file path, " +
      "line numbers, and surrounding code. More accurate than text-based Grep for finding code " +
      "by intent rather than exact string match. Use this instead of Grep when searching for " +
      "code by what it does rather than what it contains.",
    inputSchema: z.object({ query: z.string() }),
  },
  async ({ query }) => ({
    content: [{ type: "text", text: `Results for: ${query}` }],
  })
);

# Before (sparse — agent will prefer Grep):
# search_codebase: "Searches code"


# After (enhanced — agent can make an informed choice). The docstring is the
# description the model selects on, so the boundary statement belongs in it.
@mcp.tool()
def search_codebase(query: str) -> str:
    """Performs semantic code search across the entire repository using AST-aware indexing.

    Returns matching functions, classes, and methods with full context including
    file path, line numbers, and surrounding code. More accurate than text-based
    Grep for finding code by intent rather than exact string match. Use this
    instead of Grep when searching for code by what it does rather than what it
    contains.
    """
    return f"Results for: {query}"

Appendix B — Interactive Study Prompts

Two prompts to paste into Claude. B1 drills the judgement the exam actually measures; B3 reviews the code you wrote for the Build Exercise above. The exam simulator between them is the interactive quiz on this page.

B1. Concept Check — Discrimination Drill

B2. Exam Simulator

B3. Build Coach — Code Review

The Build Exercise and its hint ladder are already on this page. This prompt is for the one thing the page cannot do: review the configuration you actually wrote.