Review Questions

Three shapes, completion, chat and agents, which differ in how much they do before you look. "Completion predicts the next few lines from the code around my cursor, and I see every token before I accept it. Chat answers questions or drafts code from what I select or mention, and it only knows what's in the conversation. An agent takes a goal and runs a loop: the model proposes a tool call, read a file, edit, run the tests, the harness runs it if the permission rules allow, and the result goes back into the context until the model says it's done. They run in the editor, the terminal or the cloud; the further from me they run, the more I rely on tests and review instead of watching."

Learn more: What AI coding assistants do.

It sends the whole context to the model, receives one proposed step, checks its permission rules, runs the tool if allowed, and appends the result to the context for the next turn. "The model is stateless: it never touches a file, it only produces a request, and it learns what happened only from the result the harness puts back. So the context grows every turn and is re-sent every turn, which is the cost, and every tool call passes the harness's permission gate, which is the safety. A denial is just another tool result the model has to cope with."

Learn more: What AI coding assistants do and Copilot features at a glance.

The model predicts one token at a time from a probability over its vocabulary, and it can only see what's in its context window for that request. "A token is a chunk of text, roughly four characters of English. The context window is everything the model can look at in one request, including its own answer, and there's no memory between requests; chat history works because the harness re-sends it. What the model knows about libraries is frozen at training time and mixes versions. So anything newer or private, our codebase, our conventions, our device API, it only knows if it's in the context, and when something isn't there it reconstructs it from patterns, fluently and sometimes wrongly."

Learn more: How they work, just enough to use them well.

Because it generates the most plausible continuation, not a checked one, and no: temperature changes how probability is spread, not which names the model thinks are plausible. "After fs. the model has seen readJson from fs-extra next to plenty of fs code, so it's a plausible token even though node:fs has no such function. Low temperature makes the top-scoring name more likely; if the top name is wrong, it's wrong every time. The fix is a check in the loop: the type checker against the installed declarations, the tests, and the real docs or .d.ts in the context for anything version-sensitive."

Learn more: How they work, just enough to use them well and Spotting hallucinated APIs and subtle bugs.

That a big window makes it possible to include more, not free: quality drops as the context fills, and the one constraint that matters ends up in the middle of hundreds of thousands of tokens. "I'd give it the context the change needs: the file, what it imports, what calls it, and its tests, plus the exact error. Agents that search the repository do a version of that themselves; with chat it's my job. And a new session for a new task, so old turns aren't competing for attention."

Learn more: Give the model the context it needs and How they work, just enough to use them well.

They help most where the answer is a well-trodden pattern and checking is cheap; I'm careful, or write it myself, where correctness depends on facts the model can't see or a near-miss is expensive. "Good fits: boilerplate that follows the repo's pattern, a first draft of tests that I review, mechanical refactors with types and tests as a safety net, explaining unfamiliar code as a starting hypothesis, one-off scripts I can dry-run. Careful: auth, input handling and file paths, money and time zones, concurrency, retries, and anything using our private APIs unless I've given it the real types. The mental model is cheap to generate, expensive to verify: the value is the time saved generating minus the time spent verifying and fixing."

Learn more: Where they help and where they hurt.

It depends on the task, codebase, developer and measurement, and the careful studies disagree, so I don't quote one number. "Controlled, self-contained tasks show big speed-ups: GitHub's 2022 experiment, published as a paper in February 2023, had developers write an HTTP server 55.8% faster with Copilot. But METR's July 2025 randomised trial of 16 experienced maintainers on 246 real issues in their own large repos found tasks took 19% longer with AI allowed, while the developers believed they'd been about 20% faster. METR's February 2026 follow-up with newer tools leaned towards a speed-up, but METR itself calls that data unreliable. And DORA's 2025 report found AI adoption going with higher throughput but lower delivery stability, calling AI an amplifier of an organisation's strengths and weaknesses."

Learn more: Where they help and where they hurt and Measuring whether it helps.

The same people as for any other code: the author who opens the pull request and the reviewers who approve it. Ownership doesn't move; volume does. "So the habits have to scale: I specify done up front, ideally as a failing test; I verify with checks rather than the assistant's own claim of success, and I ask for the actual command output; and I review the diff like a colleague's, hardest on security, edge cases and tests that might assert the wrong thing. If I can't explain a line, I don't merge it. 'The AI wrote it' isn't an answer anyone accepts in an incident review."

Learn more: The developer's job with an assistant.

No. I'd check it against a slow, obviously correct oracle on generated inputs, which finds what the hand-picked examples share a blind spot with: two bugs in the sort and a missing case for even lengths. "sort() with no comparator sorts as strings, so [9, 10, 3] becomes [10, 3, 9] and the 'median' is 3, and it sorts in place, mutating the caller's array. It also never averages for even lengths. The fix is to copy, sort numerically and average the middle pair."

Learn more: The developer's job with an assistant.

Like a ticket for a contractor who can't ask questions until they hand in the work. "The goal in one line, the file to change, and the context it can't guess: the types it must use, the existing helpers, the callers that depend on it. Then the decisions only I can make: valid inputs and error behaviour, where rounding or ordering happens, what must not change, no new dependencies, our versions. One worked example pins details better than a paragraph. And I end with the definition of done, the test and type-check commands, and ask for the diff and their output as evidence."

Learn more: Give the model the context it needs.

Because the model fills every gap with the most typical behaviour it has seen, and the typical behaviour is the happy path. "'Parse durations like 1h30m' leaves open whether 90m is valid, what 1.5h does, whether there are seconds, and whether bad input throws or returns NaN. So I write inputs and outputs with units, behaviour as examples including boundaries, exact error behaviour, and non-goals, and I often ask the model to list ambiguities as questions before writing anything. The examples become the test table, so the spec is also the check."

Learn more: Spec first: describe behaviour and edge cases.

Tests first, and I own them: they're a contract with a referee, and the assistant may change its side of the line, not move the line. "I write the tests from the spec, or have the assistant draft them and review them against the spec, commit them, and run them against a stub to see them fail for the right reason. Then the assistant implements with the tests read-only, iterating on the exact failures, and shows me the real output. In review I read the test diff first, because agents told to make tests pass sometimes edit or delete the test, weaken assertions, skip tests, mock the thing under test, or special-case the test inputs."

Learn more: Tests first with an assistant and Reviewing AI-generated changes.

Evidence, not adjectives: the failing input, expected and actual values, the exact error output, and the rule it broke. "'It doesn't work' gives the model nothing new, so it changes something at random. I narrow each turn to one problem and say what not to touch, and I ask it to explain the cause in one sentence before changing code, which tells me quickly whether it understood. If the approach is wrong, I ask for two or three alternatives with trade-offs before any code. After two failed corrections I start a fresh session with a better prompt, and if the fix is smaller than the explanation, I just write it."

Learn more: Iterating and correcting.

markBatchSent runs before any notification has finished, because forEach ignores the promises its async callbacks return. "Each callback starts notify(b) and returns a pending promise straight away; forEach drops them and returns, so the batch is marked sent while the calls are in flight, and a failure becomes, at best, an unhandled rejection. I'd write await Promise.all(bookings.map((b) => notify(b))), or a for…of loop with await if they must go one at a time."

Learn more: Spotting hallucinated APIs and subtle bugs.

That it exists, is the package we meant, is maintained and has an acceptable licence, before anyone runs npm install. "Assistants invent plausible package names, and if a name gets suggested repeatedly, someone can register it with a malicious install script; that's slopsquatting. So a 404 from the registry is a block, a package created three days ago with a dozen downloads a week and one letter off a popular name is a human check, and a copyleft licence is a question for legal, not a lint rule. I'd run that check in CI on every PR that changes package.json."

Learn more: Spotting hallucinated APIs and subtle bugs and Security, licensing and data concerns.

Short, organised around data and responsibility rather than products, because products change monthly. "Which tools: company seats only, plus MCP servers we've reviewed, with a quick path to get a new one reviewed. Which data: code and internal docs are fine with approved tools; customer logs, credentials and keys never go in, and we give people a one-command redaction script so the safe path is easy. Which work: anything, but device commands, auth and migrations get a second reviewer, whoever typed them. Ownership: whoever opens the PR owns every line and says what they verified. I'd write it down in the repo, give it an owner, and revisit it quarterly."

Learn more: Setting team guidelines for AI-assisted work.

Visibility, routing by risk and the agent-specific rules; how to read the diff is the same checklist as for any PR. "The PR template asks how much was generated and what the author verified. Routing is by what the change touches, so device commands, auth and migrations get a second reviewer whoever wrote them. Size limits don't grow because an agent can produce a big diff. For Copilot cloud agent PRs, GitHub doesn't count the requester's approval and workflows don't run until someone approves them. And instruction files and MCP config are owned by the tech leads, because they change what every assistant on the team does."

Learn more: Reviewing AI-generated changes.

Three separate questions: what goes out, what comes in, and what the tools can do. "Out: company seats so business data terms apply, content exclusion for sensitive paths, and no customer logs or credentials in any tool, with a redaction script that keeps placeholders consistent so the result is still useful. In: generated code gets the normal security review, new dependencies are checked for licence, existence and age, and we choose deliberately whether to block or reference suggestions that match public code. Tools: agents run with the developer's permissions and MCP servers with their own, so approved, pinned servers, least-privilege tokens, and a human confirmation for anything that writes to a device."

Learn more: Security, licensing and data concerns.

I can't say it's working yet: most of the improvement also happened to the team without the tool, and the pilot's reverts more than doubled. "The pilot's own before/after is −33%, which is what a launch slide would say. The comparison team improved 17% with no new tools, so the part we might attribute to the pilot is about 17 points, and with a few dozen PRs per period that's likely within noise. I'd report it that way, keep the pilot running, look at which PRs were reverted and why, and run the developer survey."

// "Is the Copilot pilot working?" Before/after vs a comparison team (difference-in-differences).
// The numbers are made up for this card: median hours from PR open to merge, and reverts per month.
const teams = {
  pilot: { before: 18, after: 12, revertsBefore: 3, revertsAfter: 7 },
  comparison: { before: 18, after: 15, revertsBefore: 3, revertsAfter: 3 },
};
const pct = (a, b) => ((b - a) / a) * 100;
for (const [name, t] of Object.entries(teams)) {
  console.log(`${name.padEnd(10)} median ${t.before}h → ${t.after}h (${pct(t.before, t.after).toFixed(0)}%), reverts ${t.revertsBefore} → ${t.revertsAfter}`);
}
const own = pct(teams.pilot.before, teams.pilot.after);
const did = own - pct(teams.comparison.before, teams.comparison.after);
console.log(`pilot's own before/after:  ${own.toFixed(0)}%`);
console.log(`difference-in-differences: ${did.toFixed(0)} points (the part the comparison team didn't also get)`);
console.log(`counter-metric: reverts ${teams.pilot.revertsAfter / teams.pilot.revertsBefore > 1 ? "rose" : "held"} for the pilot only`);

pilot      median 18h → 12h (-33%), reverts 3 → 7
comparison median 18h → 15h (-17%), reverts 3 → 3
pilot's own before/after:  -33%
difference-in-differences: -17 points (the part the comparison team didn't also get)
counter-metric: reverts rose for the pilot only

Learn more: Measuring whether it helps.

Treat the team's AI setup as code in the repository, shared by both sites, and provision everyone at the same time. "One set of instruction files with the build and test commands and our 'never' rules, prompt files for jobs we repeat, like adding an endpoint or writing the end-of-day handoff, and an approved, pinned list of MCP servers, including a team-hosted device-lab server where each person signs in as themselves. Tech leads at both sites own those files, and a CI check catches contradictions, literal secrets and unpinned servers. Then a short monthly session alternating which site presents what worked and what didn't."

Learn more: Helping a distributed team use AI tools well.

One specific time from your own work, AI-related or not, told as STAR with a learning; this card gives only the shape, because the story has to be yours. "I'd open with a one-line headline, then the situation: what was going wrong without guidance. Then what I did, with a 'because' for each step: how I found out how people actually worked, what I proposed, how I got both sites to agree, how I made the compliant path the easy one. Then what I measured afterwards, and what I changed when part of it didn't work." If you haven't led an AI rollout, say so, walk through how you'd do it, and use a practice you did introduce as the evidence.

Learn more: Setting team guidelines for AI-assisted work, the Tech Lead site's Behavioural interviews chapter, and your own stories in My notes.

A family of tools that differ mainly in how much of the work Copilot does before you look at it. "At one end, inline suggestions and next edit suggestions: it proposes, I accept with Tab. Then Chat, which answers and explains. Then Plan, which researches with read-only tools and proposes steps for me to approve, and agent mode, which edits files and runs commands in my editor while I approve and review the diff. Further out, the cloud agent, which used to be called the coding agent, works alone on GitHub in an Actions environment and opens a draft pull request. Alongside those: Copilot code review on pull requests, Copilot CLI in the terminal, and the Copilot desktop app for parallel agent sessions."

Learn more: Copilot features at a glance.

(a) agent mode, (b) Ask or Plan, (c) the cloud agent, (d) do it myself, with Chat or Plan to think it through and code review plus a human reviewer on the result. "The less ambiguous and the easier to verify a task is, the further right on the dial I can turn it."

Learn more: Copilot features at a glance and Agent mode and the coding agent.

Since 1 June 2026, chat, agents, the CLI and code review consume GitHub AI Credits, priced from the tokens each interaction uses at the model's rate, with 1 credit = $0.01; completions and next edit suggestions aren't billed in credits. "Agents cost more because they make many model calls, each re-sending a growing context, not because they're priced differently. In chapter 2's model, one chat question was 1.90 credits and a 30-call agent task about 61 credits, roughly 32 chat questions. So 'keep the task small and the context lean' is a cost rule as well as a quality rule."

Learn more: Copilot features at a glance and Copilot code review.

Standing context Copilot reads automatically, written once instead of pasted into every prompt; it steers what the model is likely to do, and enforces nothing. "I'd keep it short and true for most requests: what the project is, with versions; the exact bootstrap, build, test and lint commands, because an agent that can't validate its change produces PRs that fail CI; and a handful of non-obvious rules with their reasons, like 'device calls can take seconds, never block the request thread'. Rules for one part of the code go in path-specific files. Lint, types, tests and branch protection are what enforce."

Learn more: Custom instructions and prompt files.

They're additive context selected by file path and by surface, and you shouldn't rely on precedence to resolve conflicts. "Path-specific files in .github/instructions/ have applyTo globs and apply when Copilot works on a matching file, together with the repository file. AGENTS.md, nearest one wins, or a root CLAUDE.md or GEMINI.md, are agent instructions read by the cloud agent, code review on GitHub.com and the CLI, and VS Code chat reads AGENTS.md. So a repo with a good CLAUDE.md already gives Copilot's cloud agent and code review those instructions. But GitHub.com Chat doesn't read path-specific files, and code review in VS Code reads only the repository file, so rules that must always apply go there."

Learn more: Custom instructions and prompt files.

Instructions for how to behave always; a prompt file for one job you run on demand; a skill for a kind of task loaded when relevant; a custom agent for a recurring role that needs its own tools and rules. "I start with a short instructions file. I write a prompt file, like /add-endpoint, when I notice the same multi-step prompt being retyped: it's the team's best prompt, versioned in the repo, linking the real pattern files so the agent copies them instead of inventing. And if a job needs a different tool set, like a read-only API contract checker, that's a custom agent whose tools list leaves out edit and execute, so it can't change code whatever its prompt says."

Learn more: Custom instructions and prompt files and Agent mode and the coding agent.

Because a pull request can change the instructions its own review uses, for example by deleting the security checklist. "GitHub presents it as a convenience, you can test new review instructions in the same PR, but it means instruction files, AGENTS.md and skills are part of the attack surface of review. So changes under .github/instructions/, .github/copilot-instructions.md and AGENTS.md need a code owner's approval through CODEOWNERS and branch protection, and Copilot's review is never the only control."

Learn more: Custom instructions and prompt files and Reviewing AI-generated changes.

Same loop, different place. "Both are a model in a loop with tools: read, edit, run, check, repeat. Agent mode runs in my editor on my machine and I'm in the loop: by default it asks before running commands, I can redirect it, and the result is changes in my working tree. The cloud agent, called the coding agent until April this year, runs on GitHub in an ephemeral Actions environment behind a firewall: I give it an issue, it works on a copilot/ branch for up to 59 minutes and opens a draft PR. It can't merge, the person who asked can't approve it, and by default CI doesn't run on its pushes until a human approves. So agent mode for work I want to steer, the cloud agent for small, well-specified tasks."

Learn more: Agent mode and the coding agent.

Write-access-only triggering, one copilot/ branch, a draft PR it can't approve or merge, workflows held until a human approves, a firewall, hidden-text filtering, self-checks and signed, auditable commits. "The limits I'd name: the firewall applies only to processes the agent starts with its Bash tool, not to MCP server processes or the setup steps, so an MCP server reaches whatever its own code reaches; an admin can switch the workflow approval gate off; and the MCP tools in the repository config run without anyone approving them."

Learn more: Agent mode and the coding agent.

Both are documented behaviour: the agent only saw the issue as it was at assignment, and workflows on its pushes wait for a human. "Assigning sends the title, description, existing comments and my prompt; later issue comments aren't seen. So I'd put the requirement on the pull request: start a review, mention @copilot, and submit the review so it works on all comments together. The waiting checks are the 'Approve and run workflows' gate; I'd read the diff, especially anything under .github/workflows/, then approve and let CI run."

Learn more: Agent mode and the coding agent.

Because VS Code judges each subcommand of a compound command: every one must match a true rule and none a false one. "Here git push matches a false rule, so the whole line asks; otherwise an approved prefix could smuggle anything after it. And I'd be clear that auto-approval is a convenience allowlist, not a security boundary; VS Code's own docs say so, because parsers miss subcommands and obfuscated commands can evade matching. When prompt injection is a concern, the answer is the sandbox or a container."

Learn more: Agent mode and the coding agent.

In the IDE you configure servers per workspace or user, and agent mode asks before calling their tools unless you've approved them; the cloud agent gets servers from the repository's settings and calls their tools without asking. "So for the cloud agent the MCP configuration is the permission model: every server must list its tools, ideally a short allowlist of read-only ones rather than *; secrets come only from Agents secrets named COPILOT_MCP_…; only tools are supported, not resources or prompts; and remote servers that need OAuth aren't supported. Code review is stricter again: it only uses tools whose readOnlyHint is true."

Learn more: Agent mode and the coding agent and Copilot code review.

As the first reviewer, not the last. "I'd turn on automatic review with a ruleset, Lite by default and Balanced for security-sensitive repositories, with Balanced chosen on the request for risky changes, and keep at least one human approval required. I'd put the checklist the team already applies, auth and input validation on API routes, into a path-specific instructions file, protect the instruction files with CODEOWNERS because review reads them from the PR's own branch, and measure whether it helps: how many of its comments lead to a change, and whether time to first review or escaped defects move."

Learn more: Copilot code review.

I'd separate the worries, because Copilot's controls are separate: seats, policies, content exclusion, and data terms. "Training: on Business or Enterprise, GitHub's terms say our data isn't used to train models, so company code is only worked on with company seats; since 24 April 2026 personal plans may be used for training unless the developer opts out. Sensitive files: content exclusion for things like provisioning configs, but it covers completions and chat, not agent mode, so the real fix is keeping secrets and customer data out of the repo, with secret scanning and push protection. Agents: enable the MCP policy with an allowlist in managed settings, keep the cloud agent's firewall on, and allow only read-only MCP tools there."

Learn more: Copilot for teams: policies, privacy and content exclusion.

The 55% is one lab task, not your team, and acceptance rate isn't share of code; neither is an outcome. "55.8% came from one controlled experiment on a small greenfield task, and METR's 2025 trial on real repositories found the opposite sign. An acceptance rate is the share of shown suggestions accepted; accepted text gets edited and deleted, and it says nothing about whether the code was good. What I'd say instead is which tasks I use it for, and what I'd measure on a team: time to first review, time to merge, reverts, with a baseline and a survey."

Learn more: Talking about Copilot in an interview and Measuring whether it helps.

With what's true, named precisely, in the four-part shape: task, workflow, check, result and limit. This card can't give you the content; it has to come from what you've actually done. The structure: say which assistant you use most (if it's Claude Code, say so) and what you've actually done with Copilot; describe one or two real workflows in the four parts; name one limit you hit; then say what transfers (planning before editing, instruction files, tests as the agent's check, reviewing diffs, MCP being the same protocol) and what you'd set up for a team. If your hands-on Copilot time is limited, say so and explain from the documentation how it works.

Learn more: Talking about Copilot in an interview and your own workflows in My notes.

In three steps, with a measurement. "First, guardrails before rollout: company seats only, content exclusion for sensitive paths with its limits written down, the MCP policy on with an allowlist, and branch protection so a human approves every merge. Second, shared context: a short copilot-instructions.md and AGENTS.md per repo with versions and commands, a few prompt files for our common jobs, and Copilot code review on by default. Third, a pilot with a few volunteers for a month, a weekly session on what worked and what didn't, and a baseline taken before we start: time to first review, time to merge, reverts and a short survey. Then decide on expansion from that, not from acceptance rate."

Learn more: Talking about Copilot in an interview and Setting team guidelines for AI-assisted work.

One real incident from your own work, any assistant, told so the check is the hero: what you asked, what came back, how you noticed, what you changed in your process. The card gives only the shape. Open with a headline ("an assistant's fix passed the demo but let a path escape the uploads folder; a boundary test caught it"), give the context briefly, then the detection step in detail: which check found it (a type error, a failing test, a review question, a hostile input), and why the plausible version would have shipped without it. End with the habit you kept, such as writing the boundary cases first or asking for command output as evidence.

Learn more: Spotting hallucinated APIs and subtle bugs, the Tech Lead site's Behavioural interviews chapter, and your own stories in My notes.

MCP, the Model Context Protocol, is an open standard for connecting AI applications to the tools and data they need: a system's owner writes one MCP server, and any MCP-capable application can discover and use it at runtime. "Before MCP, every AI app integrated every system its own way, so five apps and eight systems meant forty integrations. With MCP it's five clients and eight servers. A server describes three kinds of things: tools, actions the model can ask for; resources, data the application can read into context; and prompts, templates the user can pick. The AI application is the host: it runs one MCP client per server, its model decides when to call a tool, and the host asks the user before anything risky. Underneath it's JSON-RPC 2.0 messages over stdio for local servers or Streamable HTTP for remote ones, with version and capability negotiation, and an optional OAuth-based authorization scheme for remote servers. The spec says it was inspired by the Language Server Protocol, which solved the same N-times-M problem for editors and languages. Anthropic announced it in November 2024; it's now under the Linux Foundation's Agentic AI Foundation, and the current revision is 2026-07-28."

Learn more: What MCP is and the problem it solves.

Forty integrations without MCP, thirteen pieces with it: five clients and eight servers. "Point-to-point grows as N times M, a shared protocol as N plus M. When ticketing changes its API, without MCP up to five codebases owned by different teams need fixing; with MCP only the tickets server changes, and if its tool names and schemas stay the same, no host notices."

Learn more: What MCP is and the problem it solves.

The tool part is standardised function calling, but between processes and products, discovered at runtime; and a server usually uses no model at all. "Function calling in a model API is how one application lets its model call its own functions. MCP is for when a capability should be usable from more than one AI application, or is built by a different team, or you want users to plug in tools you didn't build. If it's one app, one codebase, one model calling its own function, plain function calling does it without a protocol, a process and a version to manage. And MCP isn't an LLM API or an agent framework: the host sends prompts, picks tools and runs the loop with whatever model it uses; the server just answers requests."

Learn more: What MCP is and the problem it solves.

The host is the AI application the user runs; inside it, one client per server speaks MCP to exactly that server; servers expose tools, resources and prompts, as local child processes or remote services. "Say VS Code with Copilot is the host: it owns the chat, the model and the user's consent. For each configured server it creates a client, a protocol connector. One client per server keeps them isolated: each connection negotiates its own version and capabilities, has its own auth, fails on its own, and a server only sees what its own client sends, never the conversation or another server's data. The host is where policy lives: it merges tools for the model, disambiguates names, and asks the user before risky calls. The model never talks to a server directly."

Learn more: Hosts, clients and servers.

One host, three clients, three servers, and two extra processes on the laptop. "The host is VS Code. It creates one client object per configured server, all inside its own process. The two local servers use stdio, so VS Code spawns each as a child process. GitHub's server runs on GitHub's infrastructure; the laptop only holds an HTTP connection to it, which is why it needs OAuth while the local ones take credentials from environment variables."

Learn more: Hosts, clients and servers and Transports: stdio and Streamable HTTP.

JSON-RPC 2.0: small JSON objects in four shapes. "A request has an id, a method and optional params, and gets exactly one reply. A result response echoes the id with a result; an error response echoes it with an error that has an integer code and a message. A notification has a method and no id, and nobody replies to it. MCP adds that ids are strings or integers, never null, and never reused: within a session in 2025-11-25, and while a request is still waiting for its answer in 2026-07-28, which has no sessions. In the 2025-11-25 revision both sides can send requests, and each numbers its own. On stdio each message is one line; on HTTP the client POSTs each of its messages, and the server's messages come back as JSON or on an SSE stream."

Learn more: The protocol on the wire.

A fixed opening, then numbered questions and answers. "The client sends initialize with the protocol version it wants, its capabilities, like roots or elicitation, and its name. The server answers with the version it'll use, its capabilities, say tools with listChanged, and its own info. The client sends notifications/initialized, a notification so no reply, and from then on lists tools and calls them. Capabilities are a promise: neither side uses a feature the other didn't declare. That's what the v1 SDKs, including 1.32.2, do under client.connect()."

Learn more: The protocol on the wire.

2025-06-18 is echoed because the server supports it; 2099-01-01 gets the server's latest, 2025-11-25, and the client should disconnect if it can't speak that; and server/discover gets "Method not found", which marks a legacy server. "Negotiation in 2025-11-25 is client proposes, server picks, once per connection. In 2026-07-28 it's per request: an unsupported version gets a specific error with the supported list, and the client retries."

// Version negotiation against a real SDK 1.32.2 server, by hand over the in-memory transport.
// Each probe gets a fresh server, as a fresh connection would.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";

async function ask(message) {
  const server = new McpServer({ name: "rooms", version: "1.0.0" });
  server.registerTool("list_rooms", { description: "All meeting rooms" }, async () => ({ content: [] }));
  const [client, serverSide] = InMemoryTransport.createLinkedPair();
  await server.connect(serverSide);
  const reply = new Promise((resolve) => (client.onmessage = resolve));
  await client.start();
  await client.send({ jsonrpc: "2.0", id: 1, ...message });
  const r = await reply;
  await server.close();
  return r.error ? `error ${r.error.code} ${r.error.message}` : `protocolVersion ${r.result.protocolVersion}`;
}

const init = (v) => ({ method: "initialize", params: { protocolVersion: v, capabilities: {}, clientInfo: { name: "rq", version: "0" } } });
for (const v of ["2025-11-25", "2025-06-18", "2099-01-01"]) console.log(`initialize asking ${v} → ${await ask(init(v))}`);
const probe = { method: "server/discover", params: { _meta: {
  "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {} } } };
console.log(`server/discover (2026-07-28 probe) → ${await ask(probe)}`);

initialize asking 2025-11-25 → protocolVersion 2025-11-25
initialize asking 2025-06-18 → protocolVersion 2025-06-18
initialize asking 2099-01-01 → protocolVersion 2025-11-25
server/discover (2026-07-28 probe) → error -32601 Method not found

Learn more: The protocol on the wire.

It made MCP stateless: no initialize handshake, no HTTP sessions and no server-to-client requests, so any request can go to any server instance. "Every request now carries its protocol version and client capabilities in params._meta; there's a new server/discover method if you want the server's capabilities up front; every result has a resultType; and when a server needs input mid-call, it returns input_required and the client retries the request with the answers, which the spec calls multi round-trip requests. Change notifications come from a subscriptions/listen request. The reason is scaling: 2025-11-25 sessions pinned a client to one process, so remote servers needed sticky routing; stateless servers run behind a plain load balancer."

Learn more: The protocol on the wire and Transports: stdio and Streamable HTTP.

A is legacy: fall back to the initialize handshake. B is modern but wants another revision: don't fall back; retry with a supported version if the host speaks one, otherwise report an incompatibility. "The rule is to fall back only when the reply is not a recognised modern error, and never to key that decision to one particular legacy error code, because legacy servers answer unknown methods in implementation-defined ways or not at all."

Learn more: Client features: roots, sampling and elicitation and The protocol on the wire.

A tool is an action the server offers and the model chooses to call, described by a name, a description and a JSON Schema for its arguments. "A REST endpoint is designed for a programmer who reads the docs; a tool is designed for a model that only reads its name, description and schema at runtime, and picks it itself. So the definition is the whole interface: a clear verb_noun name, a description that says when to use it, and a tight schema. Results are content blocks the model can read, optionally with structuredContent matching an output schema. Annotations like readOnlyHint help the host decide what needs confirmation. Often one tool wraps one or a few REST calls; it doesn't replace the API."

Learn more: Tools.

If the model could do something useful with the message, it's a tool error, a normal result with isError: true; if the request itself is broken, it's a protocol error. "Bad arguments, an API timeout, a business rule like 'you can't reboot that room' are tool errors, so the model can correct itself or explain. A request that doesn't fit tools/call at all is a protocol error. One variance to know: the spec lists an unknown tool as a protocol error, but SDK 1.32.2's McpServer returns it as an isError result, which at least lets the model retry with the right name."

// Which failures come back as a JSON-RPC error and which as a result with isError: true, in SDK 1.32.2.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";

const server = new McpServer({ name: "rooms", version: "1.0.0" });
server.registerTool("set_volume", {
  description: "Set a room's speaker volume",
  inputSchema: { roomId: z.string(), level: z.number().int().min(0).max(100) },
}, async ({ roomId, level }) => {
  if (roomId === "lobby") return { isError: true, content: [{ type: "text", text: "lobby has no speaker. Rooms with speakers: huddle-2." }] };
  if (roomId === "board-1") throw new Error("connect ECONNREFUSED 10.0.4.17:443");
  return { content: [{ type: "text", text: `${roomId} volume ${level}` }] };
});

const [c, s] = InMemoryTransport.createLinkedPair();
await server.connect(s);
const client = new Client({ name: "rq", version: "0" });
await client.connect(c);

const cases = [
  ["works", { name: "set_volume", arguments: { roomId: "huddle-2", level: 40 } }],
  ["isError on purpose", { name: "set_volume", arguments: { roomId: "lobby", level: 40 } }],
  ["handler throws", { name: "set_volume", arguments: { roomId: "board-1", level: 40 } }],
  ["bad arguments", { name: "set_volume", arguments: { roomId: "huddle-2", level: 140 } }],
  ["unknown tool", { name: "set_volum", arguments: {} }],
];
for (const [label, params] of cases) {
  try {
    const r = await client.callTool(params);
    console.log(`${label.padEnd(19)} result, isError=${r.isError === true}: ${r.content[0].text}`);
  } catch (e) {
    console.log(`${label.padEnd(19)} JSON-RPC error ${e.code}: ${e.message.slice(0, 60)}`);
  }
}
// A request that doesn't fit tools/call at all: no tool name.
try {
  await client.request({ method: "tools/call", params: { arguments: {} } }, CallToolResultSchema);
} catch (e) {
  const issue = JSON.parse(e.message.slice(e.message.indexOf("[")))[0]; // zod's validation issue
  console.log(`${"no name at all".padEnd(19)} JSON-RPC error ${e.code}: ${issue.path.join(".")}: ${issue.message}`);
}
await client.close();

works               result, isError=false: huddle-2 volume 40
isError on purpose  result, isError=true: lobby has no speaker. Rooms with speakers: huddle-2.
handler throws      result, isError=true: connect ECONNREFUSED 10.0.4.17:443
bad arguments       result, isError=true: MCP error -32602: Input validation error: Invalid arguments for tool set_volume: Too big: expected number to be <=100 at level
unknown tool        result, isError=true: MCP error -32602: Tool set_volum not found
no name at all      JSON-RPC error -32603: params.name: Invalid input: expected string, received undefined

Learn more: Tools and Designing good tools.

Annotations are behaviour hints, readOnlyHint, destructiveHint, idempotentHint, openWorldHint, whose defaults are deliberately pessimistic, and a host must treat them as untrusted unless the server is trusted. "A tool with no annotations is described as not read-only, destructive, not idempotent and open-world, so get_status looks as dangerous as a reboot and a host like VS Code will ask before every status check. I'd add readOnlyHint: true and openWorldHint: false to get_status, spell out the reboot's hints, and still put the reboot's real protection in the server."

// Tool annotations with their defaults filled in (2025-11-25 schema), and what a host that confirms
// every tool not marked read-only (VS Code's documented behaviour) would do with each tool.
const DEFAULTS = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true };
const tools = {
  get_status: undefined, // the colleague forgot annotations
  get_status_fixed: { readOnlyHint: true, openWorldHint: false },
  set_volume: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
  reboot_device: { readOnlyHint: false },
};
for (const [name, annotations] of Object.entries(tools)) {
  const h = { ...DEFAULTS, ...annotations };
  const shape = h.readOnlyHint ? "read-only" : `${h.destructiveHint ? "destructive" : "non-destructive"}, ${h.idempotentHint ? "idempotent" : "not idempotent"}`;
  const host = h.readOnlyHint ? "runs without asking" : "asks the user first";
  console.log(`${name.padEnd(17)} ${shape.padEnd(32)} ${(h.openWorldHint ? "open world" : "closed world").padEnd(12)}  → ${host}`);
}

get_status        destructive, not idempotent      open world    → asks the user first
get_status_fixed  read-only                        closed world  → runs without asking
set_volume        non-destructive, idempotent      open world    → asks the user first
reboot_device     destructive, not idempotent      open world    → asks the user first

Learn more: Tools, Designing good tools (VS Code's confirmation rule) and Wrapping a device REST API as MCP tools.

A resource is data identified by a URI that the application or user brings into context; a template like rooms://{roomId}/status describes a family of them. "I ask who should decide when it's used. If the user or the app should choose to attach it, a runbook, a log, a room's config, it's a resource: URI, MIME type, read-only, shown in a context picker. If the model should decide mid-task to fetch or change something, it's a tool. For important data I'd offer both, a read tool for the agent loop and a resource for explicit attachment, because hosts differ in how they surface resources."

Learn more: Resources and resource templates.

Tools, resources and prompts, and the difference is who's in control. "Tools are model-controlled: the model decides to call them, with the host asking the user for anything risky. Resources are application-controlled context identified by URIs that the host or user attaches. Prompts are user-controlled templates, usually slash commands, that expand into ready-made messages, so a team can package the right way to ask about something, like 'triage this room', with the room's status embedded. For a device platform: device reads and guarded actions as tools, runbooks and logs as resources, and a triage prompt."

Learn more: Prompts.

(a) resource, (b) tool, (c) prompt, (d) tool. "The test each time is who decides when it's used: the model is a tool, the application or user attaching data is a resource, the user starting a workflow is a prompt."

Learn more: Prompts and Adding resources and prompts.

stdio when the server is a local helper for one user; Streamable HTTP when it's shared or remote. "With stdio the host launches the server as a child process, writes JSON-RPC lines to its stdin and reads its stdout; it runs with the user's permissions, takes credentials from environment variables and is gone when the host closes: filesystem, git, a CLI wrapper, a developer's lab tools. With Streamable HTTP the server is a web service at one endpoint like /mcp: each client message is a POST, answered with JSON or an SSE stream for progress, one deployment serves many clients, it's authorised with OAuth, and you update it once instead of on every laptop."

Learn more: Transports: stdio and Streamable HTTP.

Because on stdio, stdout is the protocol channel: every line must be one valid JSON-RPC message, so logs go to stderr. "A console.log line arrives at the client as something that isn't JSON and causes a parse error; a write without a newline is worse, because it glues itself onto the front of the next real response and that response is lost, so the call hangs until its timeout. The fix is console.error, and silencing any library that prints banners or progress bars to stdout."

Learn more: Transports: stdio and Streamable HTTP and A first server with the TypeScript SDK.

In 2025-11-25 a server may create a session at initialize and return an Mcp-Session-Id header, which the client sends on every request; 2026-07-28 removed sessions, so state that spans calls travels as explicit handles in tool arguments. "With sessions, a request without the header gets a 400, an unknown or ended session a 404, and the client must start over with initialize. That state lives in one server process, so behind a load balancer you need sticky routing or shared session storage. In 2026-07-28 any instance serves any request, and gateways route on Mcp-Method and Mcp-Name headers."

Learn more: Transports: stdio and Streamable HTTP and Remote servers over Streamable HTTP.

Three client features: roots, sampling and elicitation, each available only if the client declared it. "Roots tell the server which folders or URIs the user considers in scope, as a hint, not access control. Sampling lets the server ask the host's model for a completion without its own API key. Elicitation lets the server ask the user for input: a small flat form, or for anything sensitive, a URL the user opens in a browser. In 2025-11-25 the server sends these as its own requests in the middle of a call. 2026-07-28 deprecated roots and sampling, keeps elicitation, and changed the mechanism: the server returns an input_required result and the client retries the original request with the answers."

Learn more: Client features: roots, sampling and elicitation.

It answers the tools/call with resultType: "input_required", listing the elicitation it needs in inputRequests plus an opaque requestState, and the client asks the user and retries the same call with a new id, the answers in inputResponses and the requestState echoed back. "The first request is finished and the server keeps nothing in memory, so any instance can handle the retry. Because the client carries the state, the server must treat requestState as attacker-controlled: when it affects authorisation or business logic, integrity-protect it with an HMAC or AEAD encryption and reject anything that fails verification; the spec also recommends binding it to the user, the original request and a short expiry."

Learn more: Client features: roots, sampling and elicitation and Wrapping a device REST API as MCP tools.

No. The spec says servers must not use form mode for passwords, API keys, access tokens or payment details; for those it requires URL mode, added in 2025-11-25. "In URL mode the server sends a URL, the client shows the full URL and asks for consent, and the user completes it in a browser, so the secret never passes through the client or the model. It's for the server's own third-party access on the user's behalf, not for authorising the client to the MCP server, which is MCP authorization's job."

Learn more: Client features: roots, sampling and elicitation.

Authorization is optional in the spec, but a remote server should use its OAuth 2.1-based flow: the MCP server is a resource server that checks access tokens, and the company's identity provider issues them. "A client that calls without a token gets a 401 pointing at the server's protected resource metadata, which names the authorization server. The client runs the authorization code flow with PKCE in the user's browser, sending a resource parameter so the token's audience is this specific server, then sends Authorization: Bearer on every request. The server checks signature, issuer, expiry and audience every time, answers 403 insufficient_scope when a tool needs more, and never forwards the client's token upstream. Local stdio servers skip all this and take credentials from the environment."

Learn more: Authorization for remote servers.

That a model reads one stream of tokens and can't reliably tell instructions from data, and MCP pours more outside text into that stream while giving the model more tools to act with. "So: prompt injection through tool results, like a public GitHub issue that steered an agent into leaking private repos in May 2025; tool poisoning, instructions hidden in a tool's description that the model reads and the user never sees; rug pulls, a server changing its tools after approval; and ordinary supply-chain risk, because a local server is code that runs as you. You can't filter injection reliably, so I design around Simon Willison's lethal trifecta: private data, untrusted content and a way to send data out. Remove a leg, or have a human approve the call that would complete it, plus least privilege, reviewed and pinned servers, and audit logs."

Learn more: Prompt injection and tool poisoning and Least privilege, confirmations and sandboxing.

I'd put a small MCP server in front of the device management API so support engineers and developers can ask their existing assistant about a room, read-only first. "Version one is status, settings with secrets stripped, short redacted log windows and the API docs, as tools for the model and resources for people to attach. Writes come later, one narrow operation per tool, like power-cycling one USB port or rebooting one device, scoped to the sites the person may manage, refused during a call or outside the maintenance window, rate-limited, confirmed by the person through elicitation and audited. For a support team it's a remote server with OAuth, so device credentials never touch a laptop and the audit log names a person. And I'd treat device content as untrusted, because meeting titles and device names end up in logs the model reads."

Learn more: Why expose a device API through MCP and Demo: troubleshooting a device with an assistant.

Honestly, with what you've actually done, then show the depth that the job needs; this card gives only the structure. The shape: one sentence on where you are ("I hadn't used MCP before preparing for this role; I've since studied the spec and built servers with the TypeScript SDK", only the parts that are true), then the explanation in your own words (the N-plus-M idea, host, client and server, tools, resources and prompts, the two transports, the 2026-07-28 stateless revision), then the design you'd bring to this platform (read-only first, confirmed writes, server-side guardrails), then one honest limit ("I haven't run one in production; here's what I'd watch"). If you've connected a server to a real host such as VS Code or Claude Code, name the host and what you saw; if you haven't, say so.

Learn more: What MCP is and the problem it solves, the Tech Lead site's Behavioural interviews chapter, and your own notes in My notes.

Create an McpServer with a name and version, register tools with registerTool, and connect it to a transport. "Each tool has a name, a description the model reads to decide when to use it, an input schema written in zod, which the SDK turns into JSON Schema and validates before my handler runs, and an async handler that returns content blocks, optionally with structuredContent matching an output schema. For a local server the transport is stdio, so I never write to stdout and I log to stderr. I keep the server in a createServer factory with its data layer injected, so tests connect it to the in-memory transport and the entry file only wires stdio. The SDK handles the handshake, capabilities, tools/list, validation and error wrapping."

Learn more: A first server with the TypeScript SDK and Remote servers over Streamable HTTP (SDK v2 and statelessness).

Split it into three task-shaped tools with precise schemas and honest annotations: get_room_status({ roomId }) read-only, reboot_room({ roomId }) destructive, and set_volume({ roomId, level: 0–100, duringCall }). "The model only sees the name, the description and the schema, so those are the product. This one makes the model learn a mini-language from two words, hides every field inside a JSON string the SDK can't validate, and claims to be read-only when it can reboot, which in VS Code skips the confirmation for a call that drops a meeting. That last one is the dangerous bug."

Learn more: Designing good tools.

In the zod schema, where the SDK enforces it before the handler runs and the model can see it in advance. "z.enum, .int().min(1).max(50), .regex() and .describe() become JSON Schema in tools/list, so the model reads the allowed values next to each field, and a bad call comes back as an isError result naming the field and the rule. Handler-side errors are for rules that depend on live data: this room has no speaker, that room is in a call, this user lacks the role."

Learn more: Designing good tools and Wrapping a device REST API as MCP tools.

As isError results written for the model, saying what happened and what to do next; never raw exception text, stack traces, internal addresses or credentials. "A small wrapper keeps two kinds apart: failures the model can act on, like 'huddle-2 is in a call; ask the user, then call again with duringCall: true', go through unchanged; anything unexpected becomes 'Internal error (ref E1). Don't retry; tell the user the room service failed', and the real detail goes to the server's log with the request id. Without that, SDK 1.32.2 sends the exception's own message to the model, IP address included."

Learn more: Designing good tools and Wrapping a device REST API as MCP tools.

Everything a tool returns goes into the model's context window, so a huge result is noise that displaces signal, and some hosts truncate or warn. "I'd return a short answer, like the last few matching lines, plus a resource_link to the full log that the host or the model can read if it's worth it, and page long lists with an opaque cursor. Chapter 5's version returned 336 characters instead of 173,889."

Learn more: Designing good tools and Exposing logs and docs as resources.

They're registerResource and registerPrompt calls on the same server object, sharing the same data functions as the tools; and yes, every registration returns a handle you can disable, enable, update or remove, and the SDK tells clients the list changed. "A fixed resource takes a URI; a family takes a ResourceTemplate like rooms://{roomId}/status with list and complete callbacks; a prompt takes zod string arguments, optionally completable, and returns messages that can embed resources. At runtime, reboot.disable() during a firmware rollout sends notifications/tools/list_changed, the host re-lists, and a call anyway gets 'Tool reboot_room disabled'."

Learn more: Adding resources and prompts.

Mostly in-process, through the protocol: a real SDK client connected to my createServer() over the in-memory transport, with fake data injected. "Each test does a real handshake, tools/list and tools/call in milliseconds, with the SDK's validation and error handling in the path. I assert on structuredContent for success and on isError plus the message for failures, because the message is what the model acts on. I snapshot the tool list, since names, descriptions and schemas are the model's interface. One end-to-end test spawns the real stdio entry point like a host. The MCP Inspector's CLI makes a CI smoke test: it exits 5 on a tool error. And the last check is a real host: does the model actually pick the tool and use it right?"

Learn more: Testing a server.

It depends on timing between two pipes: stdout carries the protocol and stderr the logs, and nothing orders "stderr arrived" before "the call resolved". "On a busy CI runner it can fail. Moving the assertion after client.close() fixes it, because close ends the child's stdin and waits for the process to exit, and Node emits close only after the child's streams have closed, so every stderr byte has arrived."

Learn more: Testing a server.

For a local server it's a config entry: a name, a command, arguments and environment variables; the host spawns the command, does the handshake, lists the tools and gives them to the model. "VS Code uses .vscode/mcp.json with a servers key and can prompt for secrets with input variables; Claude Desktop and Claude Code use mcpServers, in claude_desktop_config.json and a project .mcp.json. If it works in my terminal and not in Claude Desktop, the two likely causes are a relative path, because the app isn't running in my project folder, and node not being on the GUI app's PATH, for example from a version manager. Absolute paths fix both, then a full restart, and the server's log tells me which it was."

Learn more: Connecting a server to a host.

The SDK's StdioClientTransport doesn't pass the parent's whole environment: only a short safe list (HOME, LOGNAME, PATH, SHELL, TERM, USER on macOS and Linux) plus whatever the config's env names. Yes, it's good. "A developer's shell typically holds cloud keys and GitHub tokens; handing all of that to a third-party server is a launch decision MCP doesn't stop. The habit everywhere is to name every variable the server needs in env, and only those."

Learn more: Connecting a server to a host and Least privilege, confirmations and sandboxing.

Three things from the protocol and one from design: progress, cancellation, timeouts, and a job id for anything longer than a request should stay open. "If the client sends a progress token, I send notifications/progress with a rising count, a total and a message through the request's sendNotification, so the host can show it and clients can reset their timeout on progress, while still enforcing a maximum. I honour cancellation: the SDK aborts the handler's AbortSignal when notifications/cancelled arrives, and I check it between steps and pass it to fetch. And a firmware rollout across forty rooms becomes start_firmware_rollout, which returns a job id at once, and get_rollout_status, which the model calls later."

Learn more: Logging, progress and long-running tools.

The call fails at 5 seconds with MCP error -32001: Request timed out after two progress updates, and if the handler checks its signal between rooms, three rooms end up updated, not four. "So the client believes the call failed while three of four rooms changed, which is exactly the confusing state that makes long tools dangerous. Passing resetTimeoutOnProgress: true makes it succeed, because updates arrive every 2 seconds, well inside 5; a maxTotalTimeout should still cap it. And the tool should report partial results somewhere the model can query."

Learn more: Logging, progress and long-running tools.

As a Streamable HTTP service, one /mcp endpoint behind TLS with OAuth, and stateless. "In Node that's Express with the SDK's StreamableHTTPServerTransport; createMcpExpressApp gives JSON parsing and Host-header validation, and I'd add an Origin check. Stateless means a fresh server and transport per request, with any state that spans calls in a database keyed by a handle the tool returns and bound to the user id from the token. That scales behind a normal load balancer. Stateful 2025-11-25 sessions pin a client to one process: you need sticky routing and you lose sessions on restart, which is why 2026-07-28 removed them."

Learn more: Remote servers over Streamable HTTP.

Any page can make the browser send requests to 127.0.0.1, and with DNS rebinding the browser even treats them as same-origin with the attacker's page; so validate the Host header, validate Origin, bind to 127.0.0.1 and authenticate. "Host checks stop rebinding, because the browser sends the attacker's hostname; Origin checks stop ordinary cross-site requests. You want both, plus a token. This is the class of bug behind CVE-2025-49596 in the MCP Inspector, where a malicious page could ask its unauthenticated local proxy to launch any command."

Learn more: Remote servers over Streamable HTTP.

Discover, consent with PKCE, get a token bound to this server, then send it on every request. "The client's first POST has no token, so the server answers 401 with a WWW-Authenticate header pointing at its protected resource metadata. The client fetches that, learns the authorization server, fetches its metadata and picks a client id: a pre-registered one if it has one, otherwise a Client ID Metadata Document URL. It opens the browser at /authorize with a PKCE S256 challenge, the scope and resource naming the MCP server; the user logs in and consents; the browser is redirected back with a code; the client swaps the code plus the verifier for a token at /token, again with resource. Every request then carries Authorization: Bearer, which the server checks for signature, issuer, expiry and audience."

Learn more: Authorization for remote servers.

The audience check: your server rejects any token whose audience isn't its own canonical URI. "It works because the client sent resource= naming the other server when it got that token, as the spec requires on both the authorization and token requests, so the identity provider stamped the other server into aud. Scopes wouldn't help, since the token might well carry devices:read; audience is the only claim that says which server."

Learn more: Authorization for remote servers.

No. The spec says an MCP server must not accept tokens that weren't issued for it, and must not pass through the client's token to upstream APIs; it gets its own token for those. "Passthrough breaks controls that depend on the token's audience, like rate limits and monitoring, makes the upstream logs show the wrong identity, and lets a token accepted by several services carry an attacker from one to the others. The related confused-deputy problem is for proxies to a third-party authorization server: they must show their own consent page per client before forwarding."

Learn more: Authorization for remote servers.

Most of it, not all: the gaps chapter 6 found in 1.32.2 are all places where the spec wants the client to refuse or to do more than the happy path needs. "If the authorization server's metadata has no code_challenge_methods_supported, the spec says the client must refuse; the SDK builds the URL anyway. It doesn't check that the AS metadata's issuer matches where it was fetched, which RFC 8414 and 2026-07-28 require. On step-up it asks for exactly the challenged scope rather than the union. And as a 2025-11-25 SDK it has no iss check on the redirect. So when I build a host, I read the spec's MUSTs and test them against the SDK version I ship."

Learn more: Authorization for remote servers.

Prompt injection is attacker text in the model's context being followed as an instruction; tool poisoning is the variant where it hides in a server's tool description, which the model reads and the user never sees. "You can't filter it reliably, so I design around the lethal trifecta: private data, untrusted content and a way to send data out. In this session the post to #general is the call that completes it, so that's where the host asks a human, showing the full message. The cheaper permanent fix is to remove a leg: let the chat tool post only to the requester's own support channel. On top: only reviewed servers, pinned tool definitions, read-only by default, and every call logged."

// Which call completes Simon Willison's "lethal trifecta" (private data + untrusted content + a way out)?
// The session and the classification rules are made up for this card.
const legsOf = (call) => ({
  get_ticket: ["untrusted"],             // customers write tickets
  read_device_logs: ["private", "untrusted"], // hostnames and IPs, plus meeting titles anyone can type
  get_device_status: ["private"],
  post_message: call.args.channel === "#support-4411" ? [] : ["external"], // only the requester's own channel is "in"
}[call.tool] ?? []);

function replay(session) {
  const seen = new Set();
  for (const call of session) {
    const before = seen.size;
    for (const leg of legsOf(call)) seen.add(leg);
    const legs = [...seen].sort().join(" + ") || "none";
    const verdict = seen.size === 3 && before < 3 ? "  ← trifecta complete: ask a human" : "";
    console.log(`  ${call.tool.padEnd(18)} ${JSON.stringify(call.args).padEnd(28)} legs: ${legs}${verdict}`);
  }
}

console.log("session A");
replay([
  { tool: "get_ticket", args: { id: 17 } },
  { tool: "read_device_logs", args: { deviceId: "huddle-2" } },
  { tool: "post_message", args: { channel: "#general" } },
]);
console.log("session B: chat may only post to the requester's channel");
replay([
  { tool: "get_ticket", args: { id: 17 } },
  { tool: "read_device_logs", args: { deviceId: "huddle-2" } },
  { tool: "post_message", args: { channel: "#support-4411" } },
]);

session A
  get_ticket         {"id":17}                    legs: untrusted
  read_device_logs   {"deviceId":"huddle-2"}      legs: private + untrusted
  post_message       {"channel":"#general"}       legs: external + private + untrusted  ← trifecta complete: ask a human
session B: chat may only post to the requester's channel
  get_ticket         {"id":17}                    legs: untrusted
  read_device_logs   {"deviceId":"huddle-2"}      legs: private + untrusted
  post_message       {"channel":"#support-4411"}  legs: private + untrusted

Learn more: Prompt injection and tool poisoning.

Layer by layer, so each control covers another's failure. "Which tools exist: servers are read-only by default and write tools are switched on per deployment, so an injected instruction can't call something that isn't there. Credentials: per-user OAuth tokens with narrow scopes and short lifetimes for remote servers, one scoped token in the environment for local ones. Approvals: the host auto-approves reads and asks before writes, showing full arguments, and for irreversible actions the server itself asks the human through elicitation, so a lax host setting can't skip it. The process: local servers in a sandbox or container with no access to SSH keys and a network allowlist. And an audit log of every call."

Learn more: Least privilege, confirmations and sandboxing.

Like adding a dependency that also gets to talk to the model: provenance, capability, and change. "Provenance: who publishes it and whether the package really belongs to them; postmark-mcp in September 2025 was an npm look-alike of the official server whose version 1.0.16 BCC'd every email to the attacker. Capability: I read every tool description word for word, check which tools write or reach the internet, and for a local server the exact command, its environment and whether it can run sandboxed; for a remote one, the scopes it asks for. Change: I pin the version or image digest, and the host pins fingerprints of the approved tool definitions, so a changed description or a new tool is disabled until someone re-reviews it."

Learn more: Trusting third-party servers.

Ship get_device_status, read_recent_logs and get_api_docs; ship get_settings with secrets removed; leave out factory_reset and bulk_update_setting; hold reboot_device until its confirmation and guardrails exist. "Read tools carry most of the value, diagnosis, and little risk, so they go first, annotated read-only. A password in a settings result goes into the model's context, the host's logs and maybe a transcript, so the server strips it. Factory reset is irreversible and rare and stays in the admin UI. And 'any setting, any value, any number of devices' is exactly what an injected instruction would want."

Learn more: Why expose a device API through MCP.

Not by mirroring the REST API: a few task-shaped tools with tight schemas, honest annotations, and the credential held only by the server. "Get status, get settings, read recent logs, change one setting, reboot one device. Setting keys are an enum of what support may change, values validated per key. Reads are read-only and return structured content with an output schema. Writes are one device at a time, annotated honestly, destructive for reboot, idempotent for setting a value, and they confirm with the person through elicitation inside the tool. The model never sees the credential, never builds a URL and can't reach an endpoint the server didn't wrap: it gets capabilities, not access."

Learn more: Wrapping a device REST API as MCP tools.

Elicitation from the server, with host approval as a second layer; a plan/apply token proves something else. "Host approval happens before the host sends the call, but the person can click 'always allow', and on the cloud agent nobody is asked at all. Elicitation goes from the server through the client to the person, the model can't answer it, and the server receives the person's answer itself and can record it, as long as the host is one you trust to show the question. A signed plan/apply token guarantees the applied change is the planned one, same device, same state version, not expired, but the model can make both calls on its own, so it doesn't prove anyone looked."

Learn more: Wrapping a device REST API as MCP tools and Guardrails for tools that change real hardware.

Two ways, and redaction in the server. "A resource template, device://{deviceId}/logs/{log}, with completion on the device id, so a person can attach the log they mean; and a narrow tool like find-errors that returns a short answer plus a resource link, so the assistant can investigate on its own. Either way the server returns a short window and redacts secrets and personal data before anything leaves it. A system prompt saying 'never repeat passwords' or a chat UI that hides them both act after the secret is already in the model's context, where it can reach transcripts and other tools."

Learn more: Exposing logs and docs as resources.

All in the server, because the model reads attacker-writable content and annotations are only hints: the model proposes, the server disposes, the person signs. "Schema first: one device id, no bulk form. Identity and scope from authentication, never from an argument, so a person can only touch their own sites, and 'not yours' gets the same words as 'doesn't exist'. State checks right before acting: refuse during a call and outside the site's maintenance window. A rate limit per person and per fleet. A confirmation by elicitation with a message the server writes from checked facts. Apply once, no automatic retries. And every attempt, denied or applied, audited with secrets removed."

Learn more: Guardrails for tools that change real hardware.

(a) the allowlist, (b) scope, (c) the rate limit, (d) the in-call state check, (e) the per-key value rule. "The pipeline order is schema, identity and scope, allowlist and value rules, state checks, rate limit, dry run, human confirmation, apply, and each stage can deny with a reason the model can read."

Learn more: Guardrails for tools that change real hardware.

Not the model and not the labelling: per-session scope and a human confirmation for each device, both in the server. "In chapter 7's run, an unguarded server with a host that didn't confirm rebooted all three rooms. The guarded server wrapped the log in an untrusted marker, and the scripted assistant followed the instruction anyway, which is the honest result: labelling helps a real model somewhat but isn't a control. What stopped it was that huddle-2 needed the engineer's yes, and they'd asked about echo, so they declined, and board-1 and lobby-3 were outside the session's scope. None rebooted."

Learn more: Guardrails for tools that change real hardware and Prompt injection and tool poisoning.

Look, diagnose, propose, dry-run, confirm, act, verify. "Say the camera in huddle-2 stopped mid-call. The assistant lists the tools, reads the status, in a call and degraded, then the peripherals, the camera's USB port in an overcurrent state, then the log, which shows the overcurrent and the camera disconnecting in the same second. It proposes the narrowest fix that won't drop the call: power-cycle that port, not a reboot. The tool defaults to a dry run; the real call makes the server ask the engineer, 'Power-cycle USB port 2 on huddle-2? The call stays connected.' Only after a yes does it act and write an audit entry. Then it verifies by reading peripherals and status again."

Learn more: Demo: troubleshooting a device with an assistant.

Say exactly what you've done, at the level you can defend under follow-ups; this card gives only the structure. If you've run this course's models or built your own server, say what: "I've built a server with the TypeScript SDK, tested it over the in-memory transport and stdio, and run a confirmed-write flow against a simulated device", only the parts you actually ran, and with which host if any. If you haven't, say "I've studied how it works and I'd build it like this" and give the specific design: task-shaped tools, server-side guardrails, elicitation for writes, stateless HTTP with OAuth for a team. Then one honest limit, such as never having run one in production.

Learn more: Demo: troubleshooting a device with an assistant, the Tech Lead site's Behavioural interviews chapter, and your own notes in My notes.