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 exists at two levels, and confusing them is a common source of problems.
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": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
},
"jira": {
"command": "npx",
"args": ["-y", "@community/mcp-server-jira"],
"env": {
"JIRA_URL": "${JIRA_URL}",
"JIRA_TOKEN": "${JIRA_TOKEN}"
}
}
}
}
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 are 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 is 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
MCP Resources
MCP resources are a mechanism for exposing content catalogs to agents without requiring exploratory tool calls. Instead of the agent calling a tool to discover what data is available, resources present that information upfront.
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 benefit is reduced unnecessary queries. Without resources, an agent might call list_tables, then describe_table for each table, consuming multiple tool calls just to understand the data landscape. With a database schema resource, that information is available immediately.
Resources give agents visibility into available data. Tools let agents act on that data. The combination means fewer wasted calls and more targeted operations.
The Build-vs-Use Decision
This is one of the most practical decisions tested in the exam. When your team needs to integrate with an external system, the question is: build a custom MCP server or use an existing community server?
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
A subtle but important problem: 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. This happens because the model 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 is genuinely more capable than the built-in alternative.
Key Concept
Project-level .mcp.json is version-controlled and shared with the team. User-level ~/.claude.json is personal and not shared. Use ${ENV_VAR} syntax to keep credentials out of version control.
Exam Traps
Building a custom MCP server for a standard integration like Jira
Community MCP servers exist for standard integrations and should be evaluated first. Custom builds are only justified for team-specific workflows that community servers cannot handle.
Putting team-wide MCP server configuration in ~/.claude.json
~/.claude.json is user-level and personal — it is not version-controlled or shared. Team-wide servers belong in .mcp.json at the project root.
Committing credentials directly in .mcp.json instead of using environment variable expansion
Credentials in version control are a security risk. Use ${GITHUB_TOKEN} syntax so each developer sets tokens locally and secrets never enter repository history.
Leaving MCP tool descriptions sparse, causing the agent to prefer built-in tools
The model defaults to tools it understands best. Sparse MCP descriptions lose out to detailed built-in tool descriptions. Enhance MCP descriptions to explain capabilities and outputs fully.
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?
Build Exercise
Configure MCP Servers with Scoping and Environment Variables
What you'll learn
- Configure project-level MCP servers in .mcp.json for team-wide sharing
- Use environment variable expansion to keep credentials out of version control
- Distinguish between project-level and user-level MCP configuration scoping
- Expose MCP resources to reduce unnecessary exploratory tool calls
- Write enhanced MCP tool descriptions that compete with built-in tool descriptions
- Create a .mcp.json file in your project root configuring a community MCP server (e.g. GitHub) with command and args
Why: Project-level .mcp.json is version-controlled and shared with every team member who clones the repository. The exam tests whether you know that team-wide servers belong here, not in ~/.claude.json. Using community servers for standard integrations is always the correct first choice.
You should see: A .mcp.json file at the project root containing an mcpServers object with at least one server entry specifying command (e.g. npx) and args (e.g. -y @modelcontextprotocol/server-github).
- Use ${GITHUB_TOKEN} environment variable expansion for authentication credentials
Why: Committing credentials directly in .mcp.json is a security risk the exam penalises. The ${VARIABLE_NAME} syntax lets the configuration file reference environment variables without containing the actual values, keeping secrets out of repository history.
You should see: The env section of your server configuration contains ${GITHUB_TOKEN} (not an actual token value). Running git diff confirms no secrets are staged for commit. Each developer sets their own token locally.
- Add a personal or experimental MCP server to ~/.claude.json for user-level configuration
Why: User-level configuration in ~/.claude.json is personal, not version-controlled, and not shared with teammates. The exam tests whether you know the scoping hierarchy: .mcp.json for team servers, ~/.claude.json for personal or experimental servers.
You should see: A ~/.claude.json file with an mcpServers entry for a personal server (e.g. an experimental integration you are testing). This file is NOT in your project repository and NOT in version control.
- Expose a content catalogue (e.g. a documentation hierarchy or database schema) as an MCP resource
Why: MCP resources give agents visibility into available data without requiring exploratory tool calls. Without resources, an agent might call list_tables then describe_table for every table, wasting multiple tool calls. A schema resource makes that information available immediately.
You should see: An MCP resource definition that exposes structured data (e.g. a list of database tables with column types, or a documentation table of contents) accessible at a URI like db://schema/main. The resource should have a name, description, and mimeType.
- Enhance the tool descriptions for your configured MCP server to explain capabilities and outputs in detail, preventing the agent from preferring built-in tools
Why: When an MCP tool has a sparse description, the agent prefers built-in tools like Grep because their descriptions are richer and more detailed. The exam tests whether you know that enhanced MCP descriptions are required to compete with built-in tools for selection priority.
You should see: Tool descriptions that are 3-5 sentences long, explaining what the tool does, what it returns, when to use it, and how it compares to built-in alternatives. For example, a search_codebase tool description that explicitly states it is more accurate than Grep for semantic searches.
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