Task statement 2.4 · Tool design and MCP integration

Integrate MCP servers into Claude Code and agent workflows

The team builds the support agent in Claude Code, connected to its own support MCP server, the helpdesk vendor's server and GitHub's. A new engineer clones the repo and gets none of them, because of the file they were configured in.

Why it's tested

When a teammate lacks a server you have, you usually configured it in ~/.claude.json, a private file in your home directory, instead of .mcp.json, a file committed with the project. Pasting the token into .mcp.json commits the secret with the repo. The second trap is expecting a more capable MCP tool to beat built-in Grep on merit, when the model chooses by description.

KnowledgeThe file decides who gets the server

The guide calls .mcp.json, at the repository root, project scope. Every clone brings its servers, which makes it the place for shared team tooling. ~/.claude.json is user scope, never committed, so it suits personal or experimental servers. At session start Claude Code connects to every configured server in both files, and their tools are discovered at connection time and available simultaneously to the agent. An Agent SDK agent reads the same .mcp.json under its default options. So a teammate's missing server is fixed by moving it into the shared file.

Interactive · the same repo, opened on two machines

Two MCP config scopes at the top — project .mcp.json and user ~/.claude.json — flowing downward into one connection step that discovers every configured server's tools and resources at once .mcp.json project · in the repo · shared on clone ~/.claude.json user · your home directory · private references ${SUPPORT_API_TOKEN} ${GITHUB_TOKEN} from your shell, never committed from their shell, their own token expands at connection loads — it's your file not in the repo connection support, helpdesk, github + your trial server support, helpdesk, github actions content catalogs tools things to do resources things to read Every configured server connects, and all their tools are available at once. Only what was committed travels with the repo. Your trial server stays on your machine.

Your machine: both scopes connect, and every tool is available at once.

A fresh clone: the project scope arrives with the repo. The user scope never does.

On your machine both files load. Servers with different names from the two files connect side by side, and all their tools are available at once. If both files define a server with the same name, only one definition is used (see the precedence note below). The teammate gets .mcp.json because it is in the repo, and each server authenticates with their token because ${SUPPORT_API_TOKEN} and ${GITHUB_TOKEN} expand from their environment. Nothing in ~/.claude.json reaches them.

More precise than the guide. Claude Code has a third scope, local, which is the default for claude mcp add with no --scope. It is stored in ~/.claude.json under the current project's path, so it stays private to you in that one project. When one server name appears in several scopes, the whole entry from the highest wins, in the order local, project, user (checked 2026-10-01). Exam answer: project-level .mcp.json for shared team tooling, user-level ~/.claude.json for personal or experimental servers.

KnowledgeEnvironment variable expansion keeps the secret out

Environment variable expansion is how a committed file references a credential without containing it. ${GITHUB_TOKEN} in .mcp.json is replaced by the engineer's own GITHUB_TOKEN when the server connects, and ${VAR:-default} supplies a fallback. Expansion works in command, args, env, url and headers.

SkillFixing the new engineer's clone

Sam clones the repo and claude mcp list shows none of the team's servers, because they sit in Priya's ~/.claude.json with her token pasted in. The fix moves them into .mcp.json with each credential written as a variable. Before Sam exports GITHUB_TOKEN, the config still loads, but the list warns and the literal text Bearer ${GITHUB_TOKEN} is sent, so GitHub answers 401. Once he exports it, the header carries his own token.

Before

User scope, token pasted in

// ~/.claude.json (Priya only)
"github": { "type": "http",
  "url": "https://api.githubcopilot.com/mcp/",
  "headers": { "Authorization":
    "Bearer ghp_9f3K…" } }

Only Priya gets the server, and her token sits in plain text.

After

Project scope, committed

// .mcp.json at the repo root
"support": { "command": "node",
  "args": ["./mcp/support.js"],
  "env": { "SUPPORT_API_TOKEN":
    "${SUPPORT_API_TOKEN}" } },
"github": { "type": "http",
  "url": "https://api.githubcopilot.com/mcp/",
  "headers": { "Authorization":
    "Bearer ${GITHUB_TOKEN}" } }

Every clone gets the servers, and each engineer authenticates with their own token.

KnowledgeResources: a catalog instead of exploratory tool calls

A tool is an action the model calls, while an MCP resource is content a server exposes at a URI. The server lists resources with resources/list (URI, name, description) and returns content with resources/read. Resources are application-driven, meaning the host decides how they reach the model. Claude Code gives Claude tools to list and read them, and an engineer can attach one with an @ mention such as @support:docs://policies/refunds. So a content catalog exposed as resources shows what data exists in one listing, replacing exploratory tool calls.

Asked why process_refund rejected order 10024871, Claude without resources calls search_policies("refund"), then search_policies("return window"), then probes the orders table for column names. With the catalog below, one listing points it to the refund page, which gives the 90-day window.

// resources/list result from the support server (abridged)
{ "uri": "issue://summaries",
  "name": "Known-issue summaries" }
{ "uri": "docs://policies/refunds",
  "name": "Refund policy documentation hierarchy" }
{ "uri": "schema://orders",
  "name": "Orders database schema" }

More precise than the guide. Claude Code turns MCP tool search on by default: only tool names and server instructions load at session start, and Claude loads a full tool definition through ToolSearch when it needs one (checked 2026-10-01). This matters for context cost, because an extra server costs little context until its tools are used, instead of every definition costing context on every turn. Exam answer: tools from all configured servers are discovered at connection time and available simultaneously.

SkillAn existing server, or a custom one

The helpdesk vendor maintains an MCP server, so the team adds it to .mcp.json instead of wrapping the helpdesk API itself. A standard integration such as Jira works the same way: an existing community MCP server already handles authentication, pagination and API changes, so a custom one adds maintenance without adding capability. Custom servers are for team-specific workflows, like the support server enforcing the $500 refund limit.

SkillGetting the MCP tool chosen over Grep

The support server's search_tickets queries the live ticket system, yet asked which open tickets mention order 10024871, Claude prefers built-in Grep, runs it on a three-week-old exports/tickets.csv, and finds none. The description "Searches tickets" offers nothing Grep lacks, and the model chooses by description. The fix explains the tool's capabilities and outputs in detail and names the stale export it replaces.

Loses to Grep
search_tickets
"Searches tickets"

Two words against a built-in the model already knows well.

Chosen for ticket questions
search_tickets
"Search the live ticket system by
 customer ID, order number, status or
 free text. Returns ticket id, status,
 assigned agent and full comment
 history. Use this instead of local
 CSV exports, which are stale."

It says what it can do that Grep cannot, and names the alternative it should beat.

Before you add a server, ask: Should every engineer who clones this repo get this server?
Yes, it is shared team toolingPut it in .mcp.json and write every credential as ${VAR}.
No, it is personal or a trialPut it in ~/.claude.json, where it stays on your machine.
Takeaway
  • An unset ${VAR} with no default is sent as literal text, so a 401 right after cloning usually means a missing export.
  • Tools act; resources show the agent which issue summaries, docs and schemas exist in a single listing.
  • Existing servers for standard integrations like Jira, custom servers for team-specific rules, and MCP descriptions detailed enough to beat Grep.

check yourself

0 / 3 answered

An engineer on the support team wants to trial a log-search MCP server for two weeks before proposing it to the team. Until the trial ends, teammates who clone the repo should not get the server. It authenticates with an API key held in LOGS_API_KEY.Which setup best runs the trial while keeping the server off teammates' machines?

Select one.

The knowledge-base MCP server offers one tool, search_kb, over 400 policy articles. Claude Code averages seven search_kb calls per question while guessing article titles, and sometimes answers with Grep over an outdated local docs/ folder instead. Three other teams connect the same server from their own repos.Which TWO changes best fix both problems for every team that connects the server?

Select two.

Dev's Claude Code shows sandbox tickets from the helpdesk vendor's server, while teammates on the same commit see production. The committed .mcp.json has "url": "${HELPDESK_URL:-https://sandbox.helpdesk.example/mcp}". claude mcp get helpdesk reports project scope, echo $HELPDESK_URL prints an empty line, and the vendor's log shows Dev's calls reaching the sandbox host.What is the most likely root cause?

Select one.

sources

  1. Claude Code Docs, "Connect Claude Code to tools via MCP": the local, project and user scope table (local is the default; storage paths), precedence with no merging across scopes, ${VAR} and ${VAR:-default} expansion in command, args, env, url and headers, the unset-variable warning and literal text, the GitHub server URL and bearer header, tool search on by default with only tool names and server instructions loaded at session start, and resources referenced with @server:protocol://path plus tools to list and read them. Checked 2026-10-01.
  2. Claude Code Docs, Agent SDK "MCP": .mcp.json is loaded when the project setting source is enabled, which it is for default query() options. Checked 2026-10-01.
  3. Model Context Protocol, "Resources" specification (revision 2026-07-28, current): resources are application-driven, listed with resources/list and read with resources/read. Checked 2026-10-01.
  4. Project versus user scope, environment variable expansion with ${GITHUB_TOKEN}, tools available simultaneously, content catalogs (issue summaries, documentation hierarchies, database schemas), MCP descriptions versus Grep, and community servers such as Jira: Claude Certified Architect — Foundations Exam Guide v1.0, Domain 2.4. The helpdesk vendor server and the $500 limit are this course's scenario details.