2.4 Integrating MCP Servers

So far we've talked about tools abstractly. But in real projects, where do they come from? Many come from MCP servers — external programs that expose a bundle of tools (and other capabilities) to Claude through a shared standard called the Model Context Protocol. Task Statement 2.4 is about connecting these servers to Claude Code and your agents: where the configuration lives, how to keep secrets safe, and when to build your own server versus using an existing one.

Think of MCP like a universal power adapter. Before a shared standard, every integration was custom wiring — connect Claude to GitHub one way, to your database another way, to Slack a third way. MCP is the standard socket: a server speaks MCP, Claude speaks MCP, and they plug together. Connect a GitHub MCP server and Claude can read issues and open PRs; connect a Postgres MCP server and it can query your database — all through the same connection mechanism.

The headline benefit: once a server is connected, ALL of its tools are discovered automatically and become available to the agent at the same time. You don't wire up each tool individually — you connect the server, and its whole toolset shows up. This lesson is about doing that connection well, especially around scope and secrets.

The most exam-relevant decision is WHERE you configure a server, because that determines who else gets it. The exam frames this as two scopes (and current Claude Code adds a third — worth knowing both).

PROJECT scope lives in a file called .mcp.json at the project's root. Because it's a file in the repository, you check it into version control, and then everyone on the team automatically gets the same servers when they clone or pull. This is the right home for shared team tooling — the database server everyone needs, the issue tracker the whole team uses. USER scope lives in your personal config (~/.claude.json) and is private to you across all your projects — the right home for personal or experimental servers you don't want to impose on teammates.

This mirrors the CLAUDE.md hierarchy you'll meet in Domain 3.1: project-level = shared via git; user-level = personal, not shared. The signature exam scenario: a teammate isn't getting a server everyone should have — because it was configured in someone's USER scope (private) instead of PROJECT scope (.mcp.json, shared). The fix is to move it to project scope and commit it. (Current Claude Code also has a 'local' scope — private to you in one project — but project-vs-user is the distinction the exam tests.)

Project scope creates a tension: you want to SHARE the server config via git, but servers usually need secrets — API keys, tokens — and you absolutely must NOT commit secrets to a repository. How do you share the configuration without sharing the password?

The answer is environment variable expansion. In .mcp.json you write a placeholder like ${GITHUB_TOKEN} instead of the actual token. When Claude Code loads the config, it expands that placeholder using the environment variable on each person's machine. So the committed file says 'use whatever GITHUB_TOKEN is set here,' and each developer supplies their own token via their environment — the secret never enters the repository. You can also provide a fallback with ${VAR:-default}.

MCP servers expose more than just tools (actions). They can also expose RESOURCES — read-only content catalogs the agent can browse, like a list of issue summaries, a documentation hierarchy, or a database schema. The value is subtle but important: a resource lets the agent SEE what's available without making exploratory tool calls to find out. Instead of the agent calling list_issues, then get_issue, then get_issue again just to discover what exists, it can glance at a resource catalog. Tools are for DOING things; resources are for KNOWING what's there.

Finally, a judgment call the exam rewards: should you BUILD a custom MCP server or USE an existing one? The guidance is clear — for standard integrations (Jira, GitHub, Slack, Postgres), use the existing community server; reserve building a custom server for team-specific or proprietary workflows that no off-the-shelf server covers. Building custom for a standard integration is wasted effort and ongoing maintenance. One more tip: enhance your MCP tool descriptions (echoing Lesson 2.1) so the agent prefers them over built-in tools where the MCP tool is genuinely more capable.

The 2.4 traps cluster around scope (sharing vs private), secret handling, and the build-vs-use decision. Keep the project/user split and the 'use existing servers' default in mind.

• •Wrong scope for team tooling. ✗ Putting a server the whole team needs in user scope (~/.claude.json). ✓ Project scope (.mcp.json), committed to version control.
• •Committing secrets. ✗ Hard-coding an API key in .mcp.json. ✓ Use ${VAR} environment variable expansion so the secret stays out of the repo.
• •Building when you should reuse. ✗ Writing a custom MCP server for a standard integration like Jira. ✓ Use the existing community server; build custom only for proprietary needs.
• •Sparse tool descriptions. ✗ Leaving MCP tools thinly described so the agent prefers built-in tools. ✓ Enhance the descriptions (Lesson 2.1) so capable MCP tools get selected.

You now understand what MCP servers are, the project-vs-user scope decision, environment variable expansion for secrets, resources, and the build-vs-use call. The exercise puts a shared server into version control safely and proves the scope behaviour.

MCP servers supply many of an agent's tools. The final lesson of Domain 2, 2.5, turns to the tools that are always there in Claude Code — the built-in Read, Write, Edit, Bash, Grep, and Glob — and how to choose between them efficiently.