Scaffold one agent definition file that wraps one MCP server. The template lives in
references/agent-template.md; this file is the procedure.
Hard rules:
- ADDITIVE ONLY: if the target agent file already exists, switch to audit mode (compare against the template's rules, report gaps, change nothing).
- Ask ONE question at a time, each with a recommended default.
- Never write secrets into any file. Auth values are referenced as
${ENV_VAR}and the user sets them in their own shell environment.
Phase 0 — Decision gate (should this agent exist?)
Build the wrapper only if BOTH hold; otherwise say so and stop:
- A recurring task class genuinely needs this MCP server's tools.
- The server would otherwise sit in global or project MCP config, charging every session its tool schemas and instruction block regardless of use.
Counter-signal: if nearly every session of this project uses the server, wire it in the
project's .mcp.json instead — wrapping would add a dispatch hop for no isolation gain.
Phase 1 — Gather (detect first, ask only what's missing)
| Field | How to get it |
|---|---|
{{SERVER}} |
from the user's request |
{{TRANSPORT}} (http/stdio) + {{URL_OR_COMMAND}} |
server docs, or ask |
{{HEADER_NAME}} / {{ENV_VAR}} |
server docs; propose a conventional env var name |
{{TRIGGER}} |
ask: "In one sentence, when should the main conversation dispatch this agent?" — if no one-sentence answer exists, the agent should not exist (report that) |
{{TOOLS}} |
the MCP tools the task class needs (not the server's full list), plus the minimal local tools (usually Read; add Bash only if needed) |
{{MODEL}} |
default sonnet; haiku for purely mechanical operations; opus only for judgment-heavy work |
Phase 2 — Generate
Write .claude/agents/{{SERVER}}-worker.md in the project from
references/agent-template.md, replacing every placeholder. Unresolvable → literal
TODO(verify): <what>; never invent URLs, header names, or tool names.
Design rules the generated file must satisfy (also the audit checklist):
- One agent wraps ONE server — isolation comes from the 1:1.
- Server config lives ONLY in the agent's frontmatter — if the same server is also in
.mcp.jsonor global config, the isolation is fiction; flag it. - Secrets only as
${ENV_VAR}expansion. descriptionstates WHEN to dispatch it — it is the routing trigger.- Hard report caps — raw MCP payloads never flow back to the caller.
- The agent is an implementer: its results should be checked by a separate context (re-read the artifact, re-run the query), never by its own self-assessment.
Phase 3 — Smoke test (mandatory, before first real use)
- Confirm the env var is set (
test -n "$ENV_VAR"); if not, hand the user the exactexportline for their shell profile and pause. - Dispatch the new agent once with a trivial read-only task: "List what you can access; report in ≤5 bullets."
- PASS = frontmatter parsed + server connected + env resolved + a sane bullet list. FAIL = fix the agent file; do not work around it in task prompts.
Known constraint to verify per environment: agent-frontmatter mcpServers support
depends on the Claude Code version (works as of mid-2026; the smoke test is the
authoritative check). Interactively-authenticated servers (browser-login MCPs) fail in
headless/scheduled dispatch — record it in the agent's description if it applies.
Phase 4 — Report (mandatory format)
MCP-AGENT REPORT — <server>
File: .claude/agents/<server>-worker.md (created | audited)
Smoke test: PASS/FAIL + one-line evidence (verbatim)
Env var: <name> (set by user, not stored)
Dispatch trigger: <the one-sentence description>
NEXT STEPS: <only if any — e.g. unresolved TODO(verify) markers>
Print the report verbatim as your final message.