MCP Server Integration

The Model Context Protocol (MCP) is an open standard that lets Claude connect to external systems — databases, APIs, issue trackers, dev tools — through a consistent client-server interface. An MCP server exposes tools (actions), resources (readable content), and prompts. Configuring it well means the whole team shares one consistent setup instead of drifting into per-machine configuration fragmentation.

The scoping hierarchy

Where you declare a server decides who gets it. Project scope lives in .mcp.json at the repo root, is version-controlled, and is shared with everyone who clones the repo — the right home for team-wide integrations like GitHub or Jira. User scope lives in ~/.claude.json in your home directory, is personal, and is not shared — the right home for experimental or personal servers you are trialing before proposing them to the team.

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

"env": { "GITHUB_TOKEN": "ghp_aB3xR9kLm2QpZ7vN" }

"env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }

The ${VARIABLE_NAME} syntax references an environment variable instead of embedding the secret. Each developer authenticates with their own token, set through a shell profile, .env file, or secrets manager. Tokens can rotate without touching the config, and no secret ever enters repository history.

Resources vs. tools

Resources expose content that already exists so the agent can read it without spending exploratory tool calls — issue summaries, documentation tables of contents, database schemas. Tools perform actions on that data. The mental model: resources show *what data exists*; tools *do something* with it. Surfacing a schema as a resource saves Claude from a round of discovery calls just to learn table names.

Build vs. use

• Use a community server for standard integrations — GitHub, Jira, Slack, Linear, Notion. They are maintained, tested, and updated for you.
• Build a custom server only when team-specific workflows, custom business logic, or proprietary systems have no community equivalent.

Descriptions must compete

Sparse MCP tool descriptions cause Claude to prefer built-in tools that carry richer documentation. A bare "Searches code" loses to a detailed built-in every time. Describe what the tool does, what it returns, when to use it, and why it beats the alternative — the same description discipline from lesson 2.1, applied so your MCP tools actually get selected.