Chapter 4: Model Context Protocol (MCP)

Documentation: MCP | Tools | Resources | Servers

4.1 What is MCP

The Model Context Protocol (MCP) is an open protocol for connecting external systems to Claude. MCP defines three primary resource types:

Tools — functions the agent can call to perform actions (CRUD operations, API calls, command execution)
Resources — data the agent can read for context (documentation, database schemas, content catalogs)
Prompts — predefined prompt templates for common tasks

4.2 MCP Servers

An MCP server is a process that implements the MCP protocol and provides tools/resources. When you connect to an MCP server:

All tools are discovered automatically
Tools from all connected servers are available at once
Tool descriptions determine how the model will use them

4.3 Configuring MCP Servers

Project configuration (.mcp.json) — for team usage:

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

Key points:

.mcp.json is stored at the project root and managed in version control
Environment variables (${GITHUB_TOKEN}) are used for secrets—tokens themselves are not committed
Available to all project contributors

User configuration (~/.claude.json) — for personal/experimental servers:

Stored in the user's home directory
Not shared via version control
Suitable for personal experiments and testing

Choosing servers:

For standard integrations (Jira, GitHub, Slack), prefer existing community MCP servers
Build your own servers only for unique, team-specific workflows

4.4 The `isError` Flag in MCP

When an MCP tool encounters an error, it uses isError: true in the response. This signals to the agent that the call failed.

Structured error (good):

{
  "isError": true,
  "content": {
    "errorCategory": "transient",
    "isRetryable": true,
    "message": "The service is temporarily unavailable. Timeout while calling the orders API.",
    "attempted_query": "order_id=12345",
    "partial_results": null
  }
}

Generic error (anti-pattern):

{
  "isError": true,
  "content": "Operation failed"
}

A generic error gives the agent no information for decision-making—should it retry, change the query, or escalate?

4.5 MCP Resources

Resources are data that an agent can request to get context without taking actions:

Content catalogs (e.g., a list of all project tasks, hierarchical navigation)
Database schemas (understanding data structure)
Documentation (API references, internal guides)
Issue/task summaries