Skip to main content

2.4 MCP servers in Claude Code and agent workflows

Scoping​

ScopeFileShared?Use for
Project.mcp.json (repo root)Yes — version-controlledShared team tooling
User~/.claude.jsonNo — personal machinePersonal / 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​

ToolsResources
SemanticsActions the agent performsContent catalogs the agent can see
Examplescreate_issue, process_refundIssue summaries, documentation hierarchies, database schemas
PayoffEffectsReduces 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​

  1. 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?

  2. 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?

  3. 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?

  4. 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?