Integrate MCP servers into Claude Code and agent workflows

MCP servers are declared in JSON config, and the file you put them in determines who and what can see them. Two scopes matter for the exam:

• Project scope (.mcp.json at the repo root): this is shared team tooling. The file is checked into version control, so every teammate who clones or pulls the repo automatically gets the same servers. Put the servers your whole team depends on (the shared GitHub, Jira, or internal-API servers) here.
• User scope (~/.claude.json): this is personal and experimental. It applies only to you, is not shared through the repository, and is the right home for a server you are trying out or a personal tool your teammates should not inherit.

The classic diagnostic question is: a teammate does not see a server that works for you. Root cause is almost always that it was configured in your user-scoped ~/.claude.json when it should have been in the project-scoped .mcp.json that ships with the repo. This mirrors the CLAUDE.md hierarchy from Domain 3, user-level config is never shared via version control.

You can add servers with claude mcp add, and the CLI exposes a --scope flag (for example --scope project writes to .mcp.json). MCP tools are namespaced as mcp__<server>__<tool> so they never collide with built-ins.

Because .mcp.json is committed, you must never write a raw token into it. Claude Code expands environment variables inside the config at load time using ${VAR} syntax (and ${VAR:-default} for a fallback). The committed file references the variable name; the actual secret lives in each developer's shell environment or secrets manager and is substituted when the server connects.

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

Here the repo contains only the string ${GITHUB_TOKEN}. Each engineer exports their own GITHUB_TOKEN, and expansion pulls it in at connect time. Expansion works in command, args, env, and (for remote servers) url and headers, so you can parameterize endpoints and auth headers the same way.

This gives you one shared, version-controlled server definition with per-user credentials, no secret ever committed, and no need for each teammate to hand-edit the config.

When Claude Code or an Agent SDK session starts, it connects to every configured MCP server and asks each one for its capabilities (an MCP tools/list call under the hood). The tools returned by all connected servers are registered together and become available to the agent simultaneously, alongside the built-in tools. There is no per-turn loading or manual enabling of individual tools once a server is connected.

This matters for design. It ties directly back to task 2.3: because every connected server's tools land in the same shared tool space, connecting many broad servers can push the agent past the point where tool selection stays reliable. Connect the servers a workflow actually needs rather than wiring up everything available.

It also means a server that fails to start (bad command, missing token, unreachable URL) simply contributes no tools, the agent will not see them, which is another reason a teammate might report that an MCP tool 'does not exist' when the real problem is a connection or credential failure at startup.

MCP servers can expose more than tools. Resources are read-only content items, each identified by a URI, that the server advertises to the agent (via an MCP resources/list call). Think of them as a catalog the agent can see up front: issue summaries, a documentation hierarchy, database schemas, a list of available reports.

The value is reducing exploratory tool calls. Without resources, an agent that needs to know which tables exist has to call a tool, read the result, call another, and so on, burning turns and context just to discover what is available. When that catalog is exposed as resources, the agent can see the landscape directly and jump to the right action.

github://issues/summary        -> open issues with titles and labels
db://schema/orders             -> columns and types for the orders table
docs://architecture/index      -> table of contents for internal docs

So the rule of thumb: expose stable, browseable inventories (schemas, catalogs, indexes) as resources so the agent gains visibility without spending tool calls to explore, and reserve tools for actions and parameterized queries.

An MCP tool competes for selection against Claude Code's built-in tools. If your MCP tool has a thin description, the model often defaults to a familiar built-in, most commonly reaching for Grep to search text when a purpose-built MCP tool (say, a Jira search or a semantic code-search server) would give a far better result. The built-in wins by default because it is well understood and the MCP tool undersold itself.

The fix is the same principle as task 2.1: descriptions are the primary signal the model uses to choose a tool. Spell out what the MCP tool does, what inputs it takes, what it returns, and when to prefer it over the obvious built-in.

search_issues: Full-text and label search over the team's Jira project.
Returns structured issues (key, status, assignee, updated date). Prefer this
over Grep for anything about tickets, bugs, or sprint work; Grep only sees
files in the working tree, not Jira.

Calling out the boundary explicitly ('Grep only sees files, not Jira') is what nudges the agent away from the built-in and toward the more capable server.

For standard, widely-used integrations, Jira, GitHub, Slack, Google Drive, Postgres, a maintained community or official MCP server almost always exists. Adopt it rather than writing your own. You inherit maintenance, auth handling, and API-change tracking for free, and you avoid reimplementing a solved problem.

Reserve custom MCP servers for workflows that are specific to your team: a proprietary internal service, a bespoke deployment pipeline, a company-specific data store that no public server covers. That is where a custom server earns its keep, because there is no off-the-shelf alternative and the integration encodes knowledge only your team has.

The decision rule for the exam: standard integration and a good community server exists, use it; team-specific workflow with no existing coverage, build a custom server. Building a custom Jira server from scratch when a community one exists is the wrong answer, it is effort spent maintaining what someone else already maintains.