MCP: where and what
Two choices hide in every MCP question. Where is the server configured: in the repository for everyone, or on your laptop for you? What does it offer: a tool with a good description, a resource Claude can read, or an existing community server? Wrong-home and wrong-primitive options both look like real work, which is why they tempt.
D2 Tool Design & MCPExam guide 2.4 (and 2.1)About 15 minutes
Start here: the office phone list
A new office needs to call its suppliers.
.mcp.json with ${TOKEN}.~/.claude.json.- The team and CI need it: project
.mcp.json, committed, with secrets as${VARS}. - Only you, or an experiment: user-level
~/.claude.json. - A standard service (Jira, GitHub): configure a community server; build your own only for your own systems.
- Claude explores to learn what exists: publish a resource, a catalog it reads once.
- Claude ignores a better MCP tool for Grep: improve the tool's description.
Words in the question that tell you which side
Where
- “teammates”, “CI”, “on clone”: project
.mcp.json - “key”, “token”, “must not be committed”:
${VAR}expansion - “trying out”, “personal”, “only me”:
~/.claude.json
What
- “to learn which … exist”, “exploratory calls”: resource
- “still uses Grep”, “description reads only …”: better description
- “ordinary Jira tasks”, “standard integration”: community server
- “add”, “create”, “run”: a tool, not a resource
Try it: expose one need three ways
Pick a need, where you configure the server, and what it offers. The simulator shows what a new teammate and the CI job get, what lands in git, and the tool calls Claude makes in your session.
A new teammate's clone
The CI job
In git
Claude's tool calls in your session
Call counts are illustrative, chosen to show the shape. They are not measurements. Who gets the server follows the scoping rules in exam guide 2.4.
Things to try: code search + user config + one-line description: the teammate gets nothing and you get Grep. Switch to project ${VAR} + full description. Then schema + tool against + resource. Last, Jira + resource to see why a catalog can't act, and notes + project for the trap in reverse.
The three traps
| Trap | What the wrong option looks like | Why it's wrong |
|---|---|---|
| Wrong home | A team server in one engineer's ~/.claude.json; a personal experiment in the repo; a key pasted into .mcp.json | User config is not shared, so teammates and CI start without it. Committed config reaches everyone, and so does any key written in it. |
| Wrong primitive | A new or better tool when Claude is exploring what exists; a resource when Claude must act | Resources are catalogs to read; tools are actions with inputs. Exploration is a catalog problem. |
| Build or bypass | A custom Jira server; a CLAUDE.md line or hook to steer Claude off Grep | Standard services have community servers. Tool choice is driven by the tool's description, so fix that first. |
Practice: three exam-style questions
Answer first, then open “Think it through”.
Rule to remember
.mcp.json with ${VARS}; only me → ~/.claude.json. Act → tool; know what exists → resource; standard service → community server.
Exam 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.” “MCP resources expose content catalogs (issue summaries, doc hierarchies, schemas) to reduce exploratory tool calls.” “Enhance MCP tool descriptions so the agent doesn't prefer built-ins (Grep) over more capable MCP tools; prefer community MCP servers for standard integrations (Jira).”