Domain 2 · Lesson 4 · Tool Design & MCP (18%)
MCP Server Config & Built-in Tools
Task Statements 2.4 & 2.5 — where servers live, resources vs tools, and Read/Write/Edit/Bash/Grep/Glob.
Course progress: Domain 2 ▸ lesson 4 of ~4
MCP server scoping
| Scope | File | Use for |
|---|
| Project | .mcp.json (committed to repo) | Shared team tooling — everyone who clones gets it |
| User | ~/.claude.json | Personal / experimental servers, not shared |
- Use environment-variable expansion in
.mcp.json — e.g., ${GITHUB_TOKEN} — so credentials are referenced, never committed.
- Tools from all configured servers are discovered at connection time and are available simultaneously to the agent.
- Prefer existing community MCP servers for standard integrations (e.g., Jira); reserve custom servers for team-specific workflows.
MCP resources vs tools
Tools act; resources inform
Tools perform actions. Resources expose content catalogs — issue summaries, documentation hierarchies, database schemas — giving the agent visibility into available data without exploratory tool calls. If an agent is burning calls just to discover what exists, expose a resource.
Also: enhance MCP tool descriptions so the agent doesn't fall back to weaker built-in tools. A capable MCP tool with a thin description loses to Grep; a detailed description wins the selection.
Built-in tools — pick the right one
| Tool | Use for |
|---|
| Grep | Search file contents (function names, error strings, imports) |
| Glob | Find files by name/path pattern (**/*.test.tsx) |
| Read / Write | Full-file read / full-file write |
| Edit | Targeted change via unique text match |
| Bash | Run commands |
Two selection rules the exam tests
1) Edit fails on non-unique matches → fall back to Read + Write. 2) Build codebase understanding incrementally: Grep for entry points → Read to follow imports and trace flows → don't read every file upfront. To trace usage across wrapper modules: first find all exported names, then Grep each name.
Check yourself
A shared team MCP server needs a token that must not be committed. Configure it in:
~/.claude.json with the token pasted in as a literal string.mcp.json using ${TOKEN} environment-variable expansion- the root CLAUDE.md so all developers load the token on start
- a personal skill's SKILL.md frontmatter allowed-tools field
Correct: option 2. Project-scoped .mcp.json is shared via VCS; env-var expansion references the secret without committing it. ~/.claude.json is user-scoped (not shared) and pasting a literal token leaks it; CLAUDE.md and skill frontmatter don't configure servers.
Edit fails because the anchor text you targeted appears several times in the file. The reliable fallback is to:
- Retry Edit repeatedly until one of the matches happens to take
- Use Glob to locate the file and then Bash to sed-replace inline
- Read the full file, then Write it back with the change applied
- Switch to Grep to search the content and edit from the results
Correct: option 3. When Edit can't find a unique match, Read + Write is the documented reliable fallback. Retrying won't create uniqueness; Grep/Glob are search tools, not editors.
Decision rules
Shared tooling → .mcp.json + env vars. Personal/experimental → ~/.claude.json. Agent explores to find data → expose an MCP resource. Content search → Grep; filename patterns → Glob; non-unique Edit → Read+Write.
Ask your teacher. Ready for the
Domain 2 quiz. Ask first if resources-vs-tools or scoping is fuzzy.