MCP Server Integration

What You Need to Know

An MCP (Model Context Protocol) server extends Claude by connecting it to an external system. That system can be a database, an API, a development tool or an issue tracker. The way a team configures its servers decides whether the team shares one consistent toolset or has a confusing mix of different configurations.

This lesson uses one made-up example throughout: a toy shop. Its two developers use Claude Code on the shop's online store. Both need Claude to reach the store's GitHub repository and stock database. One developer also wants to trial a code search server alone.

The Scoping Hierarchy

Configuration exists at two levels. Most setup problems start when the two levels are confused.

Project level: .mcp.json. The file is in the project repository root and is version-controlled. So every team member who clones or pulls the repository gets it. Use it for servers the whole team needs: a Jira integration, GitHub tools, internal API connectors. The toy shop's GitHub and stock database servers belong in this file.

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "atlassian": {
      "type": "http",
      "url": "https://mcp.atlassian.com/v1/mcp/authv2"
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${WORKSPACE_ROOT:-.}"]
    }
  }
}

The example shows two forms of entry. A remote server declares "type": "http" and a url. A local server declares a command and args, and communicates over stdio (standard input and output). An entry with a url but no type is a configuration error. Claude Code reads it as a stdio server, skips it, and tells you to add the type.

User level: ~/.claude.json. The file is in the user's home directory and is personal. It is not version-controlled and not shared with teammates. Use it for experimental servers, personal integrations, or servers you are testing before proposing them to the team. The toy shop's trial search server belongs in this file.

All tools from all configured servers, project and user level, are discovered at connection time and available simultaneously. There is no manual activation step. If a server is configured and reachable, its tools appear in the agent's toolkit. The trial developer's Claude sees all three servers' tools.

Environment Variable Expansion

.mcp.json supports ${VARIABLE_NAME} syntax for environment variable expansion. This syntax keeps credentials out of version control whilst the server configuration stays shared.

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

The file references variable names, not values. Each developer sets their own tokens locally, in a shell profile, a .env file or a secrets manager. Each toy shop developer uses their own GitHub token. This means:

• 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

A second form, ${VAR:-default}, expands to VAR when VAR is set, and to default when VAR is not set. Use it for machine-specific paths with a sensible default, like ${WORKSPACE_ROOT:-.} above. Current state (checked 6 October 2026): an unset variable with no default does not stop the rest of the configuration loading. Claude Code warns and continues, so do not rely on a missing token to cause a visible failure.

MCP Resources

An MCP resource exposes a content catalogue to an agent upfront. So the agent needs no exploratory tool calls to discover what data exists. This description is the way exam guide v1.0 describes resources and the answer that the exam marks as correct.

Current state (checked 6 October 2026): the MCP specification says resources are application-driven. The server lists them, but the client decides when to attach one to the model's context. So the agent sees a resource only when the host, the application that contains the MCP client, shows it. Claude Code shows resources through @server:resource mentions and a resource-listing tool.

What to expose as resources:

• Issue summaries: a list of current Jira issues with titles and statuses
• Documentation hierarchies: a table of contents for your internal docs
• Database schemas: table names, column types, and relationships

The benefit is fewer wasted calls. Without resources, an agent might call list_tables, then describe_table for every table, to learn what data exists. With a database schema resource, the agent has that information immediately. For the toy shop, that resource is the shop's stock database schema.

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

The Build-vs-Use Decision

A team that integrates with an external system can build a custom MCP server or use a community server. This choice appears constantly, in the exam and in real work.

Use community servers for standard integrations:

• Jira, GitHub, Slack, Linear and Notion all have maintained community MCP servers
• They cover standard use cases, the community tests them, and they receive updates
• Using them saves development time and maintenance burden

Build custom servers only when:

• Your team has specific workflows that community servers cannot handle
• You need custom business logic embedded in the tools that the server provides
• You require integration with proprietary internal systems that have no community server

The toy shop uses a community GitHub server. The shop's stock database is internal. So if no community server covers that database, a custom connector for it is worth building.

Detailed MCP Tool Descriptions

Built-in tools such as Grep have rich, detailed descriptions, so the model has better context about them. When an MCP tool has a sparse description, the agent may prefer the built-in tool even when the MCP tool is more capable.

The fix is a description that explains capabilities and outputs in detail. Instead of:

search_codebase: "Searches code"

Write:

search_codebase: "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."

The detailed description gives the model enough context to prefer the MCP tool when it is more capable than the built-in alternative. The toy shop's trial search server needs the same kind of detailed description, or Claude may keep using Grep.

In the exam

On build-vs-use questions, the exam consistently favours the pragmatic choice. "Evaluate community servers first" is always correct when a standard integration is involved. "Build custom" is only correct when the scenario explicitly describes team-specific requirements that community servers cannot meet.

Both GitHub and Atlassian provide official remote servers now, so neither server uses an npx line in the first example.

Exam Traps

Practice Scenario

Build Exercise

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
• CCAR-F Exam Guide v1.0: Task Statement 2.4 — Anthropic