CCA-FChapters04

Chapter 04

Model Context Protocol

One flat tool namespace, config that decides who gets the server, and errors an agent can act on.

D2guide part i

4.1

Three primitives

An open protocol for plugging external systems into Claude. Everything it exposes is one of three things.

Tools

Functions the agent calls — CRUD, API requests, command execution. Side effects live here.

Resources

Data the agent reads for context — docs, database schemas, content catalogues. No action taken.

Prompts

Predefined prompt templates for recurring tasks.

Tools change the world. Resources describe it. Prompts are canned instructions.

4.2

Every server's tools land in one namespace

Connect a server and its tools are discovered automatically. All connected servers are live at once.

github servercreate_issue · get_prjira serversearch_issues · add_commentwhat the model seescreate_issueget_prsearch_issuesadd_commentone list · no server labels · overlap is yours to prevent
Nothing routes by server. The model sees one flat list and chooses by description alone.

4.3

Project config or user config

Where the file lives decides who gets the server. That is the whole question.

.mcp.json~/.claude.json
locationproject rootyour home directory
version controlcommittednever shared
who gets itevery contributor, on cloneyou only
use forthe team's shared integrationspersonal and experimental servers
secrets"env": {"GITHUB_TOKEN": "$${GITHUB_TOKEN}"}same — the value never enters the file

4.4

isError is a signal, not a message

The flag says it failed. The content has to say what the coordinator should do next.

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

Retry? Re-query? Escalate? No basis for any of them.

Actionable
{
  "isError": true,
  "content": {
    "errorCategory": "transient",
    "isRetryable": true,
    "message": "Timeout calling the
       orders API.",
    "attempted_query": "order_id=12345",
    "partial_results": null
  }
}

Category and isRetryable pick the strategy; the query and partials stop the work being redone.

Same flag, same HTTP round-trip — one of these lets the agent recover.

4.5

A resource is a map

Without one, the agent burns calls discovering what data even exists.

tools onlyagentlist_projectslist_tasksget_task ×nevery call lands in contextwith a resourceagentread: task cataloguethe whole hierarchy, one readthen act
Catalogues, database schemas, API docs, issue summaries — read once, no exploration needed.

Recall in 60 seconds

  1. MCP exposes three things: tools (act), resources (read), prompts (templates).
  2. Connected servers are discovered automatically and all their tools are available at once, in one flat list.
  3. Selection is still by description — overlap between servers is your problem to fix.
  4. .mcp.json at the project root, in VCS = the team's servers. ~/.claude.json = yours alone.
  5. Secrets go in as $${ENV_VAR}. The token itself is never committed.
  6. Standard integration → community server. Build your own only for team-specific workflows.
  7. isError: true plus "Operation failed" is a dead end — return category, isRetryable, the attempted query and any partials.
  8. A resource replaces a chain of exploratory calls with one read.