2.4 MCP servers in Claude Code and agent workflows
Scoping
| Scope | File | Shared? | Use for |
|---|---|---|---|
| Project | .mcp.json (repo root) | Yes — version-controlled | Shared team tooling |
| User | ~/.claude.json | No — personal machine | Personal / experimental servers |
Both are active simultaneously: tools from all configured MCP servers are discovered at connection time and available to the agent at once. Full configuration reference: MCP in Claude Code.
Environment variable expansion
.mcp.json expands ${VAR} so credentials never enter version control:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
},
"jira": {
"command": "npx",
"args": ["-y", "some-jira-mcp-server"],
"env": { "JIRA_URL": "${JIRA_URL}", "JIRA_API_TOKEN": "${JIRA_API_TOKEN}" }
}
}
}
MCP resources vs MCP tools
| Tools | Resources | |
|---|---|---|
| Semantics | Actions the agent performs | Content catalogs the agent can see |
| Examples | create_issue, process_refund | Issue summaries, documentation hierarchies, database schemas |
| Payoff | Effects | Reduces exploratory tool calls — the agent knows what exists without probing |
Exposing a catalog as a resource gives agents visibility into available data without requiring exploratory tool calls.
Description quality drives adoption
If MCP tool descriptions are thin, the agent prefers built-in tools it understands — reaching for Grep when a far more capable MCP search tool is configured. The fix is to enhance the MCP tool descriptions to explain capabilities and outputs in detail.
Build vs adopt
Choose an existing community MCP server for standard integrations (Jira, GitHub, Postgres). Reserve custom servers for team-specific workflows that no community server models.
Quiz
- Question 1
Your team shares a Jira MCP server every engineer needs, authenticated with a token that must not be committed. You separately run a local experimental embeddings server that only you use and that crashes frequently. How should the two be configured?
- Question 2
Your MCP server exposes search_codebase_index, which returns semantically ranked matches with file paths, surrounding context, and symbol kinds. Its description reads "Searches the codebase." Telemetry shows the agent reaching for built-in Grep on roughly 95% of searches, including conceptual questions the index answers far better. What is the most effective first step?
- Question 3
Your support agent opens most conversations with list_policies, then list_policy_sections, then get_policy_section — three calls to reach one clause, on nearly every ticket. The policy set changes about twice a year and the full text runs to roughly 80,000 words. How should this be exposed?
- Question 4
A .mcp.json committed to the repository three weeks ago contains "env": {"SUPPORT_API_KEY": "sk-live-9a…"} with the literal production key. The server is used by the whole team. What is the correct remediation?