MCP mind maps
Everything the CCA-F exam asks about MCP, on one page. Most of it comes down to four questions. Each question gets a mind map in the form "what you see, where the fault is, the fix", plus the rule to remember, the exam-guide line it comes from, and one practice question.
Domain 2 · 18%Guide 2.1–2.4About 20 minutes
First, the picture
- Tools are actions Claude can call, like
lookup_orderorprocess_refund. - Resources are read-only content Claude can look at, like a list of issues, a doc tree or a database schema.
- Prompts and sampling also exist in MCP, but the guide barely mentions them. Know their names and move on.
The four questions at a glance
| # | Question | Usual answer | Practise |
|---|---|---|---|
| 1 | Where does the server config go? | Shared: .mcp.json. Personal: ~/.claude.json. Secrets: ${VAR} | MCP: where and what |
| 2 | Tool or resource? | A resource shows a catalog so the agent stops exploring. A tool does something or fetches one thing | MCP: where and what |
| 3 | Why did Claude pick the wrong tool? | Fix the description first, then scope tools per agent, then use tool_choice for order | Tool picker, Too many tools, tool_choice, Built-in tools |
| 4 | A tool failed. What does it return? | If the tool ran, isError: true with a category and whether to retry. If the call was broken, a protocol error | Tool failure |
A yellow row in each map is the runner-up: the case where a different answer wins because one fact in the question changes.
Mind map 1: Where does the server config go?
| What you see | Where the fault is | Fix |
|---|---|---|
| The whole team needs the same server | It's in one person's personal config | Project-level .mcp.json, committed to the repo |
| One developer is trying out a server | It was put in the shared file, so everyone gets it | User-level ~/.claude.json |
A token is written into .mcp.json | A secret is committed to git | Use env var expansion: ${GITHUB_TOKEN} |
| The team needs Jira or GitHub | They plan to build their own server | Use the community MCP server |
| The system is in-house, like an orders database | No community server exists for it | Build a custom server. This is when building wins |
.mcp.json, personal config in ~/.claude.json, and secrets always go through ${VAR}. Use a community server for standard systems.Guide 2.4: “Scoping: project-level .mcp.json (shared) vs user-level ~/.claude.json (personal/experimental). Env var expansion in .mcp.json (e.g., ${GITHUB_TOKEN}) — no committed secrets.”
- Each developer adds the server to
~/.claude.json - Add it to
.mcp.jsonin the repo, with the token as${GITHUB_TOKEN} - Add it to
.mcp.jsonwith a shared team token - Describe the server in
CLAUDE.md
Mind map 2: Tool or resource?
| What you see | Where the fault is | Fix |
|---|---|---|
| The agent makes many search or list calls just to find out what exists | Nothing shows it the catalog up front | Expose the catalog as an MCP resource (issue summaries, a doc tree, a schema) |
| The agent must change something, like creating an issue or refunding an order | — | That's a tool |
| The agent needs one specific record, like order 4411 | — | That's a tool with an input |
| The content changes on every request or needs parameters | A fixed resource would be out of date or too big | A tool wins here |
Guide 2.4: “MCP resources expose content catalogs (issue summaries, doc hierarchies, schemas) to reduce exploratory tool calls.”
list_tables and then describe_table about a dozen times. How do you cut those calls?
- Merge the two tools into one
explore_dbtool - Tell the agent to call
describe_tableless often - Expose the database schema as an MCP resource
- Raise the agent's tool-call limit
Mind map 3: Why did Claude pick the wrong tool?
| What you see | Where the fault is | Fix |
|---|---|---|
| Two similar tools get mixed up | The descriptions are short or overlap | Rewrite the descriptions: input format, example queries, edge cases, and when not to use it |
One generic tool like analyze gets used wrongly | The tool does too many jobs | Split it into purpose-specific tools with clear inputs and outputs |
| Claude uses Grep instead of your more capable MCP tool | The MCP tool's description is weak | Improve the MCP tool's description. Don't remove Grep |
| One agent has 18 tools and picks badly | It has too many tools | Split the work so each agent has the 4 or 5 tools for its role |
| A subagent uses a tool outside its job | Tools aren't scoped to roles | Scope tools per agent. A few shared tools are fine if every role uses them often |
A tool must run first, like extract_metadata | tool_choice is auto, so Claude may skip it | Force it: {"type":"tool","name":"extract_metadata"} |
| Any tool call is fine, but never a plain-text reply | auto allows text | tool_choice: "any", not a forced tool |
tool_choice. An extra line in the system prompt is usually the weaker answer.Guide 2.1: “Tool descriptions are the primary mechanism LLMs use for selection.” Guide 2.3: “Too many tools (18 vs 4-5) degrades selection reliability.” Guide 2.4: “Enhance MCP tool descriptions so the agent doesn't prefer built-ins (Grep) over more capable MCP tools.”
get_customer (“Gets customer”) and lookup_account (“Looks up account”). It often calls the wrong one. Best fix?
- Add a routing table to the system prompt
- Rewrite both descriptions with what each returns, example inputs, and when to use the other one
- Merge them into one
customer_tool - Force
get_customerwithtool_choice
Mind map 4: A tool failed. What does it return?
First ask one question: did the tool run? If the call itself was broken, the tool never ran. If the tool ran and its work failed, the result says so.
| What you see | Where the fault is | Fix |
|---|---|---|
| Unknown tool name, or a required argument is missing | The call is broken, so the tool never ran | A JSON-RPC protocol error |
| The tool ran, but the downstream API failed (even with a 404) | The work failed | A result with isError: true, which Claude sees and can act on |
| The agent keeps retrying something that can never work | The error only says “Operation failed” | Add errorCategory, isRetryable and a plain-language description |
| A timeout | Transient error | isRetryable: true |
| A policy blocks the refund | Business-rule error | retriable: false and a customer-friendly explanation |
| “No results”, but the system was actually down | An access failure looks like an empty result | Make these two clearly different responses |
| A subagent sends every small error to the coordinator | It escalates too early | Recover locally. Send up only unresolved errors, with the partial results |
isError: true, with the category and whether retrying makes sense. Never send a bare “failed”.Guide 2.2: “MCP isError flag communicates failures back to the agent. Distinguish transient (timeouts), validation (bad input), business (policy), permission errors. Uniform ‘Operation failed’ prevents good recovery decisions.”
- A JSON-RPC protocol error
isError: truewith the text “Operation failed”isError: true, categorybusiness,retriable: false, and a short reason the agent can tell the customer- An empty success result
isError, and the details stop pointless retries. A is for broken calls. B works, but the agent can't decide what to do. D hides the failure.Two traps that catch people
1 · Protocol error or isError?
Ask “did the tool run?” A 404 from the downstream API sounds like a protocol error, but the tool ran, so it's isError. Newer versions of the MCP spec suggest isError for bad arguments too. On the exam, follow the guide. More on Exam vs 2026, item 5.
2 · “Add it to the system prompt”
When one option fixes the description, the tool scope or tool_choice, it usually beats an option that only adds a prompt instruction. A prompt asks Claude to comply, while a fix to the tool setup removes the cause.
How to study this
Related: Domain 2 hub · MCP skeletons · Exam vs 2026 · all traps · CCA-F start here