CCA-F Study Day 22/20: Developer Productivity Scenario — MCP Integration & Tool Distribution Deep Dive

Review Cycle Day 2 — MCP Integration & Tool Distribution Deep Dive

Cross-Domain Focus: Domain 2 (Tool Design & MCP, ~20%) + Domain 3 (Claude Code, ~20%)

---

📌 Today's Focus

Yesterday's Day 21 covered the Agent SDK's agentic loop mechanics (Domain 1). Today we shift to one of the highest-probability exam scenarios: Developer Productivity with Claude. This scenario tests your understanding of how MCP, built-in tools, and Claude Code configuration work together in a real development workflow.

This is a 40% exam weight topic (Domain 2 + Domain 3 combined). If you nail this scenario, you've covered almost half the exam.

---

🧠 Core Concepts: The MCP Architecture (Memorize This)

The Three-Layer Model

┌─────────────────────────────────────────┐
│           MCP Host                       │
│    (Claude Code, Claude Desktop)         │
│                                          │
│  ┌──────────┐    ┌──────────┐           │
│  │MCP Client│    │MCP Client│           │
│  └─────┬────┘    └─────┬────┘           │
└────────┼────────────────┼────────────────┘
         │                │
    ┌────┴─────┐    ┌────┴──────┐
    │MCP Server│    │MCP Server │
    │(Local)   │    │(Remote)   │
    └──────────┘    └───────────┘

• Host — The AI application (Claude Code, Claude Desktop). Coordinates all clients.
• Client — Maintains a 1:1 connection to an MCP server. Each client talks to exactly one server.
• Server — Exposes capabilities: Tools, Resources, and Prompts.

Two Protocol Layers

Layer	What It Does	Format
Data Layer	Lifecycle management, primitive operations, notifications	JSON-RPC 2.0
Transport Layer	Communication channels between client and server	STDIO (local) or Streamable HTTP (remote)

Three Core Primitives — The "USB-C Ports" of MCP

Primitive	Purpose	Discovery	Execution
Tools	Executable functions the AI can invoke	tools/list	tools/call
Resources	Data sources providing contextual info	resources/list	resources/read
Prompts	Reusable templates for structured interactions	prompts/list	prompts/get

Exam trap: The exam will ask about the difference between Tools vs Resources. Toolsare actions (they change state or compute something). Resources are read-only data feeds. If the exam says "provide a file listing to Claude" — that's a Resource. If it says "execute a database query" — that's a Tool.

MCP Lifecycle (5 Steps)

1. Initialize — Client sends initialize with its capabilities
2. Capability Negotiation — Both sides declare supported features
3. Initialized Notification — Client signals readiness
4. Normal Operation — Tool discovery, execution, resource access
5. Shutdown — Graceful connection termination

// Initialize Request — know this JSON structure
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "elicitation": {} },
    "clientInfo": { "name": "example-client", "version": "1.0.0" }
  }
}

---

🔧 Built-in Tools & Tool Distribution

Claude Code's Built-in Tool Inventory

Tool	Category	What It Does
Read	File operations	Read file contents
Edit	File operations	Modify existing files
Write	File operations	Create new files
Glob	Search	Find files by pattern
Grep	Search	Search content with regex
Bash	Execution	Run shell commands
WebSearch	Web	Search the web
WebFetch	Web	Fetch and parse pages
Agent	Orchestration	Spawn subagents
Skill	Orchestration	Invoke skills
ToolSearch	Discovery	Dynamically find tools on-demand

Parallel vs Sequential Execution

• Read-only tools (Read, Glob, Grep, MCP tools marked read-only): Run concurrently
• State-modifying tools (Edit, Write, Bash): Run sequentially
• Custom MCP tools: Default sequential. Set readOnlyHint in annotations for parallel execution.

Exam scenario: "A developer wants to speed up codebase exploration. Which approach is correct?"  ✅ Use Glob + Grep concurrently (both are read-only)  ❌ Use Edit + Write concurrently (state-modifying = sequential only)

ToolSearch for Scale

When you have many MCP servers exposing dozens of tools, don't preload all of them. Use ToolSearch to dynamically discover and load tools on demand. This prevents the "too many tools" anti-pattern (18+ tools causes selection confusion).

---

⚠️ Anti-Patterns & Exam Traps

❌ Anti-Pattern	✅ Correct Approach	Why It's Wrong
18+ tools on a single agent	4-5 tools per agent, distributed via MCP servers	Too many tools causes selection confusion — Claude picks the wrong tool
Generic error messages ("Operation failed")	Include isError, errorCategory, isRetryable, context	Claude can't decide whether to retry, escalate, or try an alternate path
Empty results returned as success	Distinguish "no data found" from "access failed"	Agent proceeds as if data doesn't exist when access was actually blocked
Vague tool descriptions ("Does database stuff")	Describe WHEN to use, WHAT it returns, parameter constraints	Claude can't distinguish between overlapping tools
Hardcoding tool configs in prompts	Use MCP server configuration in settings.json	Not portable, not auditable, breaks when environment changes
Preloading all MCP tools	Use ToolSearch for dynamic discovery at scale	Bloats context, causes selection confusion

---

💻 Code Examples

1. Adding an MCP Server to Claude Code

# Add a Playwright MCP server for browser automation
claude mcp add playwright -- npx @anthropic/mcp-playwright

# Tool naming convention after adding:
# mcp__playwright__browser_screenshot
# mcp__playwright__browser_navigate
# Pattern: mcp__<server_name>__<action>

2. Structured Error Response Pattern (The Right Way)

import json

def execute_tool(tool_name: str, tool_input: dict) -> dict:
    """Execute a tool and return structured results."""
    try:
        result = run_actual_tool(tool_name, tool_input)
        
        # Success — return clean result
        return {
            "type": "tool_result",
            "tool_use_id": tool_input["id"],
            "content": json.dumps(result)
        }
    except RateLimitError as e:
        # ✅ Rich error: Claude knows to wait and retry
        return {
            "type": "tool_result",
            "tool_use_id": tool_input["id"],
            "content": json.dumps({
                "error": f"Rate limited: {e.retry_after}s",
                "errorCategory": "rate_limit",
                "isRetryable": True,
                "retryAfterSeconds": e.retry_after,
                "suggestion": "Wait and retry automatically"
            }),
            "is_error": True
        }
    except AuthenticationError as e:
        # ✅ Non-retryable: Claude knows to escalate
        return {
            "type": "tool_result",
            "tool_use_id": tool_input["id"],
            "content": json.dumps({
                "error": "Authentication failed",
                "errorCategory": "authentication",
                "isRetryable": False,
                "suggestion": "Ask user to re-authenticate"
            }),
            "is_error": True
        }

3. MCP Configuration in settings.json

{
  "permissions": {
    "allowedTools": ["Read", "Glob", "Grep", "Bash(npm test*)"],
    "blockedTools": ["Write(/etc/*)"],
    "permissionMode": "acceptEdits"
  },
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-playwright"]
    }
  }
}

4. Tool Distribution Pattern — Developer Productivity System

# Architecture for a dev productivity system:
#
# Main Agent (4 tools):
#   - Glob (find files)
#   - Grep (search content)
#   - Read (view files)
#   - Agent (spawn specialists)
#
# Subagent: Code Modifier (3 tools):
#   - Edit (modify files)
#   - Write (create files)
#   - Bash (run tests)
#
# MCP Server: Database (3 tools):
#   - mcp__db__query
#   - mcp__db__schema
#   - mcp__db__migrate
#
# MCP Server: CI/CD (2 tools):
#   - mcp__ci__run_pipeline
#   - mcp__ci__get_status
#
# Total: 12 tools across 4 contexts (never >5 per agent)

---

🎬 Video to Watch

Building Agents with Model Context Protocol — Full Workshop with Mahesh Murag (Anthropic)

Led by Mahesh Murag from Anthropic's Applied AI team at AI Engineer Summit. This 80-minute workshop covers:

• 0:00 – 9:39: What is MCP (architecture, primitives, philosophy)
• 9:39 – 26:25: Building with MCP (hands-on implementation)
• 26:25 – 1:13:15: MCP & Agents (most relevant to today's exam topic — tool integration with agents)
• 1:13:15+: What's next for MCP

Focus on the 26:25–1:13:15 section for maximum exam relevance.

---

📖 Reading

• Primary: MCP Architecture Documentation
• Secondary: Anthropic Tool Use Overview
• Deep dive: Building more efficient AI agents with MCP (Anthropic Engineering)

---

🛠️ Hands-On Exercise (20 min)

Design a Developer Productivity MCP System

You're building a system where Claude Code helps developers explore a large monorepo. Design the complete tool architecture:

1. List the built-in tools the main agent needs (max 5)
2. Design 2 MCP servers with their tools (name, description, input_schema for each)
3. Write the settings.json that configures permissions + MCP servers
4. Explain which tools can run in parallel vs sequential and why
5. Handle the scenario: "MCP server goes down mid-operation" — write the structured error response

Bonus: If you have Claude Code installed, actually add an MCP server with claude mcp add and explore the tool naming convention.

---

📝 Quick Quiz

Q1. A developer's Claude Code setup has 22 tools from 3 MCP servers. Performance is degrading and tool selection is unreliable. What is the BEST architectural fix?

A) Increase the context window size B) Add better tool descriptions to each tool C) Use ToolSearch for dynamic tool discovery and distribute tools across subagents D) Disable the least-used MCP server to reduce tool count

Q2. In the MCP architecture, which statement is TRUE?

A) An MCP Client can connect to multiple MCP Servers simultaneously B) An MCP Client maintains a 1:1 connection to exactly one MCP Server C) MCP Servers communicate directly with each other D) The MCP Host and MCP Client are the same component

Q3. A tool returns an empty array [] when a database query finds no matching records. Another tool returns an empty array [] when the database connection fails. What anti-pattern does this demonstrate?

A) Too many tools per agent B) Generic error messages C) Silently suppressing errors (returning empty results as success) D) Missing parameter descriptions

---

Answers

Q1: C — Use ToolSearch + subagents. The root problem is too many tools in one context. Better descriptions (B) help marginally but don't solve the selection confusion from 22 tools. Disabling a server (D) loses functionality. ToolSearch + distribution keeps all capabilities while maintaining the 4-5 tools-per-agent sweet spot.

Q2: B — Each MCP Client maintains a 1:1 connection to exactly one MCP Server. The MCP Host manages multiple Clients (one per server). Servers are isolated and never communicate directly.

Q3: C — Silently suppressing errors. Both "no results" and "connection failed" return the same output, so Claude can't distinguish between "the data doesn't exist" and "I couldn't reach the database." The correct approach is to return a structured error with is_error: true, errorCategory: "connection", isRetryable: truewhen the database fails.

---

🔮 Tomorrow's Preview

Day 23: Structured Data Extraction Scenario — JSON Schema design, forced tool_use, validation-retry loops, and the multi-pass extraction pipeline. This is the most code-heavy exam scenario.