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:

1. Tools — functions the agent can call to perform actions (CRUD operations, API calls, command execution)
2. Resources — data the agent can read for context (documentation, database schemas, content catalogs)
3. 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

Resource advantage: the agent does not need exploratory tool calls to understand what data exists. A resource provides an immediate “map.”

---