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.
share
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
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.
.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.
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.
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.
search_tickets
"Searches tickets"Two words against a built-in the model already knows well.
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.
| Yes, it is shared team tooling | Put it in .mcp.json and write every credential as ${VAR}. |
| No, it is personal or a trial | Put it in ~/.claude.json, where it stays on your machine. |
- 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.