Integrate MCP servers into Claude Code and agent workflows

Where the config lives decides who gets the tools

MCP servers are registered by scope, and the scope is a collaboration decision. Two of them are what the certification grades:

• Project-level .mcp.json — checked into the repository. Use it for shared team tooling, so every engineer who clones the repo picks up the same servers.
• User-level ~/.claude.json — per-developer. Use it for personal or experimental servers that should not be imposed on the team.

Claude Code itself has a third scope, local, which is what claude mcp add writes when you pass no --scope flag. It also lives in ~/.claude.json, but scoped to one project rather than all of them. The exam contrasts shared versus personal, and those are the two above. So if a stem's options include a scope the guide never names, that is not the credited answer. Knowing it exists is what saves you the "I added the server and it vanished in my other repo" afternoon.²⁷

Because project config is committed, it must never contain secrets. .mcp.json supports environment variable expansion — write ${GITHUB_TOKEN} in the config and let each developer or CI runner supply the value from their own environment. The config is shareable; the credential is not.²⁷

Discovery is at connection time, and it is cumulative

Tools from all configured MCP servers are discovered when the client connects, and they are all available to the agent simultaneously. Two consequences follow. First, you do not select a server per request — everything configured is in play, which is exactly why 2.3's tool-count discipline matters when you add servers. Second, a server that fails to start simply contributes no tools, so a "missing tool" symptom is usually a connection or credential problem rather than a selection problem.²⁹

Competing with the built-in tools

An MCP tool sits alongside the built-ins (Read, Grep, Glob, and the rest), and the model picks between them on description alone. A thin description loses: the agent falls back to Grep even when a purpose-built MCP tool would answer the question in one call with better structure. Enhance MCP tool descriptions to explain capabilities and outputs in detail — say what the tool indexes, what it returns, and why it beats a raw text search — or the more capable tool goes unused.

Buy before you build, and publish a catalog

For standard integrations, choose an existing community MCP server — Jira is the guide's example — and reserve custom servers for team-specific workflows the community cannot know about. Custom servers are maintenance you own forever.

Finally, expose content catalogs as MCP resources: issue summaries, documentation hierarchies, database schemas. A resource gives the agent visibility into what data exists without a sequence of exploratory tool calls to find out — it replaces search-to-discover with read-the-index.²⁸

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

{
  name: 'find_symbol_references',
  description:
    'Finds every call site of an exported symbol using a pre-built symbol index, ' +
    'not text matching. Resolves re-exports and wrapper modules, so it finds ' +
    'callers that reference the symbol under an aliased name — which Grep cannot. ' +
    'Ignores comments, strings and generated files. ' +
    'Input: symbol name plus optional package scope. ' +
    'Output: array of {file, line, enclosingFunction, isTest}. ' +
    'Prefer this over Grep for "who calls X" questions across the repo.',
}

{
  "resources": [
    { "uri": "repo://schemas/index",
      "name": "Database schemas",
      "description": "All table and column definitions for payments, orders and accounts." },
    { "uri": "repo://docs/tree",
      "name": "Documentation hierarchy",
      "description": "Titles and paths of every ADR and runbook, grouped by service." },
    { "uri": "jira://issues/open/summary",
      "name": "Open issue summaries",
      "description": "Key, title and component for every open issue in the PAY project." }
  ]
}