Agents & MCP Field Guide

How much control should I hand to the AI for this task, and which controls should I never hand over?

Copilot can now edit dozens of files, run your build, start helpers that work in parallel, call your databases through MCP and open a pull request. Every one of those powers is optional. The skill is picking the right amount for each job, and writing down the rules that hold however much you hand over.

Prompts guide. Hooks and servers enforce.

Each module adds a layer. Every lab in the course wiki has a guided Part A and a less-guided Part B with hints. This guide explains the why behind both.

The model is the brain. The agent is the role it plays. The harness is the engine that runs the loop, applies permissions and calls tools.

• Model: a specific model, or Auto, which picks per request and is 10% cheaper.
• Agent: Ask, Plan, Agent, or a custom agent such as the course's Orchestrator. An agent is a persona plus a tool list plus, optionally, a model and hooks.
• Harness, chosen with Session Target: Local (VS Code's own loop, used in most labs), Copilot (the Copilot CLI engine), Claude, Codex, and Cloud (runs remotely, returns a PR).

A model on its own only writes text. An agent works because the harness offers the model a menu of tools (read, search, edit, execute, start a subagent, and every tool from your MCP servers). When the model replies with a tool request, the harness checks the rules, runs it, and feeds the result back. The loop repeats until the model answers in plain text.

Hooks, tool names and some settings are harness-specific. A Local hook uses events like PostToolUse and fields like tool_name; the Copilot harness reads the same .github/hooks folder but uses Copilot CLI's camelCase events and payloads. That's why the hook labs pin Session Target → Local.

The Agents window (Stable since 1.120, May 2026) is built for assigning and reviewing many agent sessions: worktrees, Dev Containers, scheduled automations, a Changes panel and Create PR. VS Code has shipped weekly since 1.111 (March 2026), so screens drift fast. When a menu has moved, search the Command Palette.

• The whole context is re-sent every step. Caching makes repeats cheaper, not free.
• Tool results pile up. File reads, test logs and big MCP results outweigh what you typed.
• Every enabled tool costs tokens every turn. An MCP server with 40 tools you never use isn't free.
• Subagents multiply. Each has its own context and its own bill.

Code completions and Next Edit Suggestions don't use credits. Check the live price list before relying on numbers.

An Agent turn can run 10 to 40 tool calls. Under token billing, Ask with good context is often genuinely cheaper. Reach for Agent when the work needs doing, not just knowing.

More autonomy is not always better.

The context is everything the model sees on a turn. The window is the most it can hold, in tokens.

A fresh chat doesn't know your other chat. A subagent doesn't know its parent's history. An MCP server's tool descriptions are in every request; its results pile up as the session runs. If something must survive, write it somewhere that gets loaded: instructions, a skill, a plan file.

The measurable drop in quality as input grows, long before the window is full.

• Lost in the middle. Early instructions in a long session end up in the middle, where models use them least.
• Distractors. An old stack trace or the previous version of a file actively misleads.
• Symptoms: forgets a rule it followed an hour ago, reintroduces a fixed bug, rereads files, invents names.

Researches with read-only tools, asks clarifying questions, and writes a reviewable plan before any code changes.

Run /plan …. In the Local harness the plan lives in session memory (/memories/session/plan.md); then choose Start Implementation or Open in Editor to tweak it first. A plan file is externalized memory: it survives compaction and new sessions.

Nothing in the editor undoes a DELETE on prod.

Repo instructions travel with every request: Ask, Plan, Agent, custom agents and subagents. They are not used for inline ghost-text suggestions.

Prove they were used: expand References under an answer, or find the text in the Chat Debug view's system prompt. A harmless "canary" rule (end every response with "📏 repo rules applied") makes it visible.

One short file of project-wide rules that every agent tool reads. Custom agents define roles; AGENTS.md defines shared standards. Nested files per folder are experimental in VS Code (chat.useNestedAgentsMdFiles).

• The name must match the folder and be lowercase with hyphens. A bad name fails silently; it's the number one "my skill doesn't show up" cause.
• The description is the trigger. Say what it does and "Use when…", in the words users type.
• Scripts must print. An agent can only use what a script writes to the terminal.
• Vite projects are ES modules. A .js script with require() crashes there. Use import, or name it .cjs.
• disable-model-invocation: true makes a skill run only via /name; user-invocable: false hides it from the menu.

A PostToolUse hook runs npm run build after every file edit. If it fails, the hook returns a structured block with the compiler output, and the agent fixes its own mistake.

{ "hooks": { "PostToolUse": [
  { "type": "command", "command": "node .github/hooks/scripts/build-validator.cjs", "timeout": 120 }
] } }

// on failure, print and exit 0:
{ "decision": "block",
  "reason": "The project no longer builds. Fix the errors below.",
  "hookSpecificOutput": { "hookEventName": "PostToolUse",
    "additionalContext": "npm run build failed: Could not resolve ./BatteryWidget …" } }

Events: SessionStart · UserPromptSubmit · PreToolUse · PostToolUse · PreCompact · SubagentStart · SubagentStop · Stop. A Stop hook can say "not done yet" (guard it with stop_hook_active, or it loops and bills).

---
name: Orchestrator
description: Breaks work into phases and delegates. Never writes code.
model: ['Claude Sonnet 5.5 (copilot)', 'GPT-5.6 Terra (copilot)']  # list = fallbacks
tools: ['read/readFile', 'agent', 'vscode/memory']                 # no edit!
agents: ['Planner', 'Designer', 'Coder']                           # who it may call
---

• user-invocable: false hides a specialist from the picker; it's subagent-only.
• disable-model-invocation: true is the reverse: humans can pick it, agents can't call it. Good for an independent reviewer.
• Nesting is off by default (chat.subagents.allowInvocationsFromSubagents, max depth 5).
• No setting is needed any more to use custom agents as subagents.

"Copilot coding agent" is now called Copilot cloud agent in GitHub's docs.

Bounded, testable, PR-shaped, reviewable.

The incident lab delegates a retry bug: the service hammers a rate-limited provider, ignoring Retry-After. The issue states symptoms, suspected cause, acceptance criteria and how to validate (npm test). Issue quality decides PR quality.

Delegate a bounded task, then review the PR like it's yours.

Copilot thinks. Servers act. Servers enforce.

A server can also ask the user a question mid-call (elicitation, Chapter 19).

RAG retrieves documents into the prompt. MCP calls live systems and returns structured results, and can take actions. They combine: a docs server like Context7 is retrieval exposed over MCP, which is why the course's Coder agent checks it before writing code.

request       {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"run_sql_query","arguments":{…}}}
result        {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"[…]"}]}}
error         {"jsonrpc":"2.0","id":3,"error":{"code":-32602,"message":"Unknown tool"}}
notification  {"jsonrpc":"2.0","method":"notifications/initialized"}      ← no id, no reply (HTTP 202)

// .vscode/mcp.json
{
  "inputs": [{ "type": "promptString", "id": "catalog-key", "description": "API key", "password": true }],
  "servers": {
    "service-db": { "type": "stdio", "command": "node",
                    "args": ["${workspaceFolder}/mcp-server/stdio-server.js"] },
    "catalog":    { "type": "http", "url": "http://localhost:4000/mcp",
                    "headers": { "Authorization": "Bearer ${input:catalog-key}" } }
  }
}

• Trust: workspace servers inherit Workspace Trust. Others show a trust dialog the first time.
• HTTP servers: the Restart lens only reconnects. It doesn't run node for you.
• Stale tools: VS Code caches tools/list. After changing tools, restart the server or run MCP: Reset Cached Tools.
• Install from the gallery: search @mcp in the Extensions view.
• Debug: MCP: List Servers → Show Output shows the handshake and errors.

Change a tool's description to "Utility function" and Copilot stops calling it. Write "Query the service inventory (table services: name, owner, environment, criticality). Use for questions about which services exist…" and it calls it immediately, with better SQL.

• The model chooses individual tools, not servers. A server is a toolbox.
• Parameter descriptions matter too: valid values in the description mean fewer probing queries.
• The Chat Debug view shows exactly what the model saw about your tool.

Your tool description is prompt engineering.

Nobody told Copilot the table names. Because the tool accepts raw SQL, it probes: SELECT name FROM sqlite_master, then PRAGMA table_info(services). That's clever, and it's also exactly why raw SQL is dangerous: the same freedom that discovers can also DROP TABLE.

server.registerTool("get_service_health", {
  title: "Get service health",                                   // what humans see
  description: "Current health snapshot for one service: status, " +
               "error rate and p95 latency.",                    // what + when
  inputSchema: z.object({ service: z.string().regex(/^[a-z0-9-]+$/) }),
  outputSchema: Health,                                          // typed results
  annotations: { readOnlyHint: true, idempotentHint: true },     // behavior hints
}, async ({ service }) => {
  const snapshot = await lookup(service);
  return { content: [{ type: "text", text: JSON.stringify(snapshot) }],
           structuredContent: snapshot };                        // both!
});

• One job per tool, named verb_noun.
• Tight inputs: enums, ranges, patterns. Invalid input never reaches your handler.
• Output schema: the SDK refuses to send results that break your own contract ("Output validation error").
• Annotations (readOnlyHint, destructiveHint…) are hints for UX and approvals. Clients mustn't trust them from unknown servers.
• Bound your output: a 100,000-line log eats context and credits. Cap it and say so in the description.

• Resources: catalog://schema or a template like catalog://services/{name}. In VS Code, Add Context → MCP Resources. The answer uses the record without a tool call.
• Prompts: /service-catalog.incident-brief asks for service and symptom, then sends a ready-made task. Arguments can autocomplete (completable()).
• Server instructions: one paragraph added to the system prompt of every client. "Prefer list_services over raw SQL. Never guess owners."

Mid-call, the server asks the user a structured question (a small form), and continues with the answer.

decommission_service asks "Decommission analytics-worker (dev, low criticality, owned by Data Team)?" with a confirm box and a reason. Decline, and nothing is deleted.

const app = createMcpExpressApp({ host: "127.0.0.1" });   // Host-header allow-list on
app.all("/mcp", requireApiKey,                            // bearer token, constant-time compare
  (req, res) => mcp(req, res, req.body));                 // createMcpHandler: stateless, both eras
app.listen(4000, "127.0.0.1");                            // loopback only

• DNS rebinding: a malicious web page makes your browser call 127.0.0.1 under its own hostname. Checking Host and Origin stops it (wrong Host → 403, even with the token).
• Secrets: ${input:catalog-key} with "password": true keeps the key out of the repo.
• Next step: OAuth 2.1 so the server knows who, not just "someone with the key".

"sandbox": {
  "filesystem": { "allowWrite": ["${workspaceFolder}/data"], "denyRead": ["~/.ssh", "~/.aws"] },
  "network":    { "allowedDomains": ["registry.npmjs.org"] }
},
"servers": { "service-catalog": { "type": "stdio", "command": "node",
  "args": ["${workspaceFolder}/mcp-server/catalog-server.js"], "sandboxEnabled": true } }

Tool calls to sandboxed servers are auto-approved, because the sandbox is the safety net. Admins can require it.

The official debugging client: a web UI, a CLI and a TUI in one package. It shows the handshake, tool schemas, raw requests and responses, HTTP status codes and stderr.

npx @modelcontextprotocol/inspector                        # web UI (opens a URL with a session token)
npx @modelcontextprotocol/inspector --cli node server.js --method tools/list
npx @modelcontextprotocol/inspector --cli http://localhost:3333/mcp --transport http \
    --protocol-era legacy --method tools/call --tool-name run_sql_query --tool-arg "query=SELECT 1"

Needs Node 22.19+. If Copilot is the black box, the Inspector is the glass box.

Lab 3.10 hides three protocol bugs in one server. Each shows a different symptom:

Packages moved from @modelcontextprotocol/sdk (v1) to @modelcontextprotocol/server and /client (v2), with z.object(…) schemas from zod/v4. A model trained before mid-2026 will happily write v1 code, which is exactly the case for a docs MCP server.

import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";

const server = new McpServer({ name: "hello-mcp", version: "1.0.0" });
server.registerTool("ping",
  { description: "Connectivity check. Use when asked to test the MCP connection.",
    inputSchema: z.object({}) },
  async () => ({ content: [{ type: "text", text: "pong" }] }));

console.error("started");          // stderr only — stdout is the protocol
await server.connect(new StdioServerTransport());