2.4 MCP Server Integration

What You Need to Know

MCP (Model Context Protocol) servers extend Claude’s capabilities by connecting it to external systems — databases, APIs, development tools, issue trackers. Configuring them correctly determines whether your team shares a consistent toolset or descends into configuration chaos.

The Scoping Hierarchy

MCP server configuration lives at two levels, and mixing them up is where most setup problems start.

Project-level: .mcp.json Lives in the project repository root. Version-controlled. Shared with every team member who clones or pulls the repository. Use this for servers that the entire team needs — your Jira integration, your GitHub tools, your internal API connectors.

{
  "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:-.}"]
    }
  }
}

Note the two entry shapes. A remote server declares "type": "http" and a url. A local one declares a command and args, and speaks over stdio. 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. Both GitHub and Atlassian ship official remote servers now, which is why neither is an npx line.

User-level: ~/.claude.json Lives in the user’s home directory. Personal. NOT version-controlled. NOT shared with teammates. Use this for experimental servers, personal integrations, or servers you’re testing before proposing them to the team.

Key principle: all tools from all configured servers (both project-level and user-level) are discovered at connection time and available simultaneously. There’s no manual activation step — if a server is configured and reachable, its tools appear in the agent’s toolkit.

Environment Variable Expansion

The .mcp.json file supports ${VARIABLE_NAME} syntax for environment variable expansion. This is how you keep credentials out of version control whilst still sharing server configuration with your team.

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

Each developer sets their own tokens locally (in their shell profile, .env file, or secrets manager). The .mcp.json file references the variable names, not the values. 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

There is a second form worth knowing: ${VAR:-default} expands to VAR when it is set and falls back to default when it is not. Use it for machine-specific paths that have a sensible fallback, as in the ${WORKSPACE_ROOT:-.} argument above. As of 14 August 2026, an unset variable with no default does not stop the rest of the configuration loading. Claude Code warns and carries on, so do not rely on a missing token failing loudly.

MCP Resources

MCP resources expose content catalogues to agents without requiring exploratory tool calls. Instead of calling a tool to discover what data exists, the agent gets that information upfront.

That is the exam guide’s framing and the keyed answer. One precision from the MCP specification (September 2026): resources are application-controlled. 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 surfaces it. Claude Code does that through @server:resource mentions and a resource-listing tool.

Examples of 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 payoff is fewer wasted calls. Without resources, an agent might call list_tables, then describe_table for every table, burning tool calls just to get its bearings. With a database schema resource, it knows immediately.

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

The Build-vs-Use Decision

This decision comes up constantly, in the exam and in real work. Your team needs to integrate with an external system: build a custom MCP server, or use an existing community one?

Use community servers for standard integrations:

Jira, GitHub, Slack, Linear, Notion — these all have maintained community MCP servers
They cover standard use cases, are tested by the community, and 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 tool layer
You require integration with proprietary internal systems that have no community server

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.

Enhancing MCP Tool Descriptions

Here’s a subtle one: when an MCP tool has a sparse description, the agent may prefer built-in tools (like Grep) even when the MCP tool is more capable. The model simply has better context about built-in tools — their descriptions are rich and detailed.

The fix: enhance your MCP tool descriptions to explain 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 enhanced description gives the model enough context to prefer the MCP tool when it’s genuinely more capable than the built-in alternative.

Exam Traps

Practice Scenario

A team needs to integrate with Jira for issue tracking in their Claude Code workflow. A developer proposes building a custom MCP server. What is the correct first step?

A. Build a custom MCP server exposing exactly the Jira API endpoints the team needs, so the integration matches their workflow precisely.
B. Add the Jira integration to ~/.claude.json so that each developer can configure their own connection to Jira independently.
C. Use the Jira REST API directly from Bash commands instead of MCP, which avoids the whole server setup and its configuration.
D. Evaluate existing community MCP servers for Jira and only build custom if they cannot handle team-specific workflows.

Answer & explanation

Correct: D

A — Building custom is premature. Community MCP servers for Jira already exist and cover standard use cases. Custom builds should be reserved for team-specific workflows that community servers cannot handle.
B — A team-wide integration should be in project-level .mcp.json so it is version-controlled and shared with all developers. ~/.claude.json is for personal servers.
C — Direct API calls bypass the MCP tool interface, losing the benefits of tool descriptions, structured responses, and agent-native integration.
D — Community servers should always be the first choice for standard integrations. They are maintained, tested, and cover common use cases. Custom builds are justified only when community servers cannot meet team-specific requirements.

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

Exam Simulator

Five exam-style multiple-choice questions on MCP Server Integration. Pick an answer, then open the explanation.

Question 1

A team needs to integrate with Jira for issue tracking in their Claude Code workflow. A developer proposes building a custom MCP server. What is the correct first step?

A. Evaluate the existing community MCP servers for Jira, and build custom only if none covers the team’s workflow.
B. Build a custom MCP server with the exact API endpoints the team needs.
C. Call the Jira REST API directly from Bash commands rather than going through MCP at all, which avoids the server entirely.
D. Add the Jira integration to ~/.claude.json so each developer configures it independently.

Answer & explanation

Correct: A

A is correct because a community server is the first thing to reach for on a standard integration. They are maintained, tested and already cover the common cases, which leaves a custom build justified only where team-specific requirements genuinely are not met.
B is wrong because building custom before looking is premature. Community MCP servers for Jira already exist and handle standard use cases.
C is wrong because direct API calls bypass the MCP tool interface, giving up tool descriptions, structured responses and agent-native integration.
D is wrong because a team-wide integration belongs in project-level .mcp.json, where it is version-controlled and shared. ~/.claude.json is for personal servers.

Question 2

A developer commits the following to .mcp.json: {“env”: {“GITHUB_TOKEN”: “ghp_abc123xyz789”}}. What is the security problem?

A. The token format is invalid for GitHub.
B. The token belongs in ~/.claude.json rather than in .mcp.json.
C. The literal credential is committed to version control instead of using ${GITHUB_TOKEN} expansion.
D. env is not a valid field in .mcp.json, so the configuration will be silently ignored when the server starts.

Answer & explanation

Correct: C

C is correct because a credential written straight into .mcp.json enters the repository history and is readable by anyone with access, including after it is deleted. The ${GITHUB_TOKEN} syntax keeps the value on each developer’s machine.
A is wrong because the token is syntactically valid, ghp_ prefix and all. The problem is that it is exposed, not that it is malformed.
B is wrong because moving the file does not help while the value is still hard-coded. The fix is environment variable expansion, not a different location.
D is wrong because env is a valid field. What is wrong here is the value it holds, not the key.

Question 3

An agent makes 5 tool calls just to understand a database structure: list_tables, then describe_table for each of 4 tables. What MCP feature would reduce these exploratory calls?

A. Caching the tool responses at the server so that every subsequent schema request returns faster.
B. Adding a get_full_schema tool that returns every table description in a single call up front.
C. Including the schema in the system prompt so that the agent already knows the structure before it starts work.
D. Exposing the database schema as an MCP resource, so it is available without any tool call.

Answer & explanation

Correct: D

D is correct because MCP resources expose a content catalogue, a database schema being the textbook case, at connection time. The structure is simply there, so list_tables and describe_table never need to run.
A is wrong because caching speeds up repeat calls but leaves the first five in place, and the first five are the ones being paid for here.
B is wrong because one call is better than five yet still a call. A resource supplies the same information with none.
C is wrong because the system prompt is the wrong home for structured data. It costs context tokens on every single request and goes stale the moment the schema changes.

Question 4

A team has project-level servers in .mcp.json and a developer has personal servers in ~/.claude.json. When Claude Code connects, which tools are available?

A. Only the project-level tools, since .mcp.json takes precedence over user configuration.
B. Every tool from both levels, discovered at connection time and available at once.
C. Only user-level tools, since personal configuration overrides the project settings entirely.
D. Neither, until the developer explicitly activates one server level for the current session.

Answer & explanation

Correct: B

B is correct because tools from all configured servers, project-level and user-level alike, are discovered when Claude Code connects and are then available together. Neither level overrides the other and nothing has to be switched on.
A is wrong because user-level servers are not excluded. Both levels contribute their tools.
C is wrong because project-level servers are not overridden. Both levels contribute their tools.
D is wrong because there is no activation step. Discovery happens automatically at connection time.

Question 5

An MCP tool named search_codebase has the description “Searches code.” The agent consistently prefers the built-in Grep tool instead. Why, and what is the fix?

A. The MCP tool is slower than Grep, so the agent optimises for speed.
B. The sparse MCP description loses to Grep’s detailed one, so expand it to cover capabilities and output.
C. Built-in tools always take priority over MCP tools, whatever their descriptions happen to say.
D. The tool should be renamed grep_enhanced to signal that it supersedes the built-in Grep.

Answer & explanation

Correct: B

B is correct because the model prefers the tool it understands best. Grep arrives with a detailed built-in description while “Searches code” says almost nothing, so expanding it to cover what the tool returns and when to prefer it over Grep is what shifts the choice.
A is wrong because the agent has no performance data. It selects on descriptions, not on measured speed.
C is wrong because built-in tools carry no inherent priority. Selection turns on description quality and relevance to the query.
D is wrong because naming an MCP tool to impersonate a built-in one adds confusion rather than removing it. The description is what needs the work.