What you will be able to do
- Design per-user OAuth for a remote MCP server that replaces a stdio server running on one developer's token
- Rename or remove a tool without stranding connected agents, using list-change notifications, isError results and a deprecation window
- Explain how the stateless 2026-07-28 protocol revision and dual-era servers behave during rolling deploys and client migrations
- Use managed MCP configuration in Claude Code so every user in a fleet gets the same servers
Key concept
Additive-first change to an MCP server — Connected clients build against the tool names, input schemas, auth requirements and protocol version that a remote MCP server publishes. Make every change by adding the new form first, and remove the old form only after clients have moved. A change that removes or renames something while clients still use it breaks agents that are in the middle of a run.
1.Per-user OAuth for a shared remote server
A local stdio server and a remote server shared by hundreds of people need different authentication designs. Over stdio, the MCP authorization flow is not meant to be used, and the server takes its credentials from the environment. That is why one developer's API token in an environment variable works on a laptop. When the same server moves to HTTP for a whole company, the server has to learn who is calling from the request itself.
On HTTP the design is OAuth 2.1. The MCP server publishes Protected Resource Metadata (RFC9728), and clients use that document to find the authorization server. A request without a token gets a 401 response whose WWW-Authenticate header points to that metadata URL. The client then sends a resource parameter in both the authorization request and the token request. The parameter names the server's canonical URI, such as https://mcp.example.com/mcp, so the token is valid for this server's audience only. The token goes in the Authorization: Bearer header and never in the query string.
Per-user visibility follows from this. The server accepts only tokens issued for its own audience, then calls the backend with the signed-in user's delegated access. Each user therefore sees only the rows that user is allowed to see. Three common shortcuts fail this requirement:
- A shared team key with the user's email passed as a tool argument. The identity is whatever the model writes into that argument.
- VPN access plus device certificates in front of one service credential. This proves the device is on the network, but every query reaches the backend as the same account.
- Non-expiring personal keys mapped to a service account. These identify the user, but the keys never expire and the backend still sees only the service account.
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
scope="files:write",
resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
error_description="File write permission required for this operation"The two error codes ask for different fixes. A 401 means authorization is missing or the token is invalid. A 403 with insufficient_scope means the token is valid but lacks a permission. In the 403 case the client re-authorizes with the union of the scopes it already requested and the scopes in the challenge, so it keeps the permissions it already has. It retries only a few times before it treats the failure as permanent.
Checkpoint 1 of 8· Fill the gap
A client calls a tool with a valid access token that does not include the files:write permission the operation needs. Which error value completes the server's challenge?
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error=" ? ",
scope="files:write",
resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
error_description="File write permission required for this operation"The token is valid but lacks a permission, so the server returns 403 with insufficient_scope. The client then re-authorizes with the scopes it already asked for plus the new scopes from the challenge. A missing or invalid token gets a 401 instead.
Source: modelcontextprotocol.ioCheckpoint 2 of 8· Check yourself
A team moves its stdio MCP server to a remote HTTP server shared by the whole company. Each employee must see only the backend records they are allowed to see. Which design meets this requirement?
Isolation comes from a token that authenticates the user and is bound to this server's audience, with the server then acting on the backend as that user. An email in a tool argument is text the model wrote, and the VPN and service-account designs make every query reach the backend as the same account.
“OAuth or per-user headers so each user authenticates as themselves.”Source: code.claude.com
Checkpoint 3 of 8· Exam question
Basalt Travel runs an internal stdio MCP server that lets its booking assistants look up itineraries and invoices; it read one developer's API token from an environment variable. The company is moving it to a remote deployment shared by 400 employees across agencies. Auditors require that every backend request be attributable to the specific employee who triggered it, and that each employee see only their own records, since the backend already enforces per-user record access. Security also wants no credentials that outlive an employee's departure, and a past review flagged tool arguments chosen by the model as untrusted input. Which authentication design is best?
Correct answer: C — Sign users in with OAuth and accept only tokens issued for this server's audience, then call the backend with that user's delegated access.
- A. VPN membership and device certificates identify a machine or network location, not the person using the server. The backend still sees a single shared credential, so nothing limits a caller to their own records.
- B. The email is chosen by the model, so a user or an injected prompt can ask for someone else's records. A team-wide key identifies no individual, and the service account hides the real caller from the backend.
- C. Correct: users authorize individually, the server accepts only tokens minted for its own audience, and the backend receives the user's delegated identity. Record scoping is enforced by the backend, not left to the caller.
- D. Non-expiring static keys sitting in client config files cannot be rotated or revoked cleanly, and a leaked file gives lasting access. The service-account call also hides the user from the backend, so scoping relies on the server's own mapping.
Sources1
2.Renaming and removing tools without stranding agents
Tool names and input schemas are the contract agents are built against. Clients cache the tool list, and prompts deployed elsewhere mention tools by name. Renaming search_tickets to find_tickets therefore removes search_tickets, whatever the release is called. Any client still using the old name will fail on its next call.
The first protection is the change notification. A client opens a subscriptions/listen request with toolsListChanged: true, and the server sends notifications/tools/list_changed on that response stream whenever its tools change. The client then re-fetches the list instead of calling a definition that no longer exists. Restarting every client application at the moment the deploy finishes is not a substitute. The server cannot trigger those restarts, and any session already running still holds the old list.
The second protection is the kind of error a stale call produces. When a client calls a name that is not registered, the server returns a protocol-level JSON-RPC error (-32602, Unknown tool). A tool execution error is different: it arrives as an ordinary result with isError: true and text content that the model reads. For a recently removed tool, return that kind of result, and make its text name the replacement and say to retry with it. The agent can then correct itself mid-run. An empty success is the worst option, because the agent carries on as if the action had happened.
{
"jsonrpc": "2.0",
"id": 4,
"result": {
"content": [
{
"type": "text",
"text": "Failed to fetch weather data: API rate limit exceeded"
}
],
"isError": true
}
}A rename needs a deprecation window, the same lifecycle Anthropic uses when it deprecates a model: the old form still works, a replacement is named, and a retirement date is announced. Publish find_tickets, keep search_tickets as a deprecated alias for a stated period, and watch how many calls still use the old name. Remove the alias once that volume reaches zero. Two other approaches fail. A major version bump with a changelog note helps nobody whose prompt is pinned and never reads the changelog. Mapping unknown names to the most similar registered tool runs a tool the agent did not choose.
Checkpoint 4 of 8· Check yourself
Your team will deploy a server release that removes a tool. Some agent sessions will still be running when the deploy finishes, with the old tool list cached. What lets those running clients find out that the list has changed, so they re-fetch it instead of calling the removed tool?
Clients cache the tool list and re-fetch it only after notifications/tools/list_changed arrives on the response stream of their subscriptions/listen request. The server cannot trigger client restarts, and a session that is already running keeps the old list. Sending a call to a similar tool runs a tool the agent did not choose, and a changelog does not reach agents whose prompts are pinned.
“Long-lived change notifications (such as list changes and resource updates) are delivered on the response stream of a subscriptions/listen request.”Source: modelcontextprotocol.io
Checkpoint 5 of 8· Exam question
Kestrel Media runs a production MCP server that exposes publishing tools to several independent agent applications owned by different editorial teams. The next deployment removes a tool that agents use to schedule article placements, and a replacement tool with a different name takes over. Clients load the tool list when a session starts and keep it for the whole session, so long-running agents will still hold the old definition after the deploy. Kestrel cannot coordinate restarts across the teams' applications, and editorial policy says a placement must never appear as scheduled unless it actually was. The removal must not leave connected agents acting on stale cached tool definitions. Which TWO behaviors make this removal safe for connected agents? Select TWO.(Select 2)
Correct answers: A, B — Emit a tool-list-changed notification so connected clients re-fetch the tool list instead of acting on stale cached definitions.; Return a structured error for removed-tool calls naming the replacement and advising a retry, so the agent can self-correct mid-run.
- A. Correct: the protocol's list-changed signal tells clients their cache is stale.
- B. Correct: an actionable error lets the agent recover instead of looping on an opaque failure.
- C. Coordinated restarts across independent clients aren't feasible, and in-flight work is lost; the server should signal instead.
- D. Empty success misleads the agent into believing the action happened, which is silent data loss for write-type tools.
- E. Many clients cache the list for a session, so removal without signaling causes calls to a tool that no longer exists.
Checkpoint 6 of 8· Exam question
Driftwood Grocers runs a support agent platform that calls an internal MCP server to look up customer tickets. The platform team renames the tool search_tickets to find_tickets in a minor release. Within an hour, agent runs that previously succeeded start failing with unknown-tool errors in several client apps owned by other teams. Those apps are pinned to older prompts and few-shot examples that still name the old tool, and some keep tool lists cached from earlier sessions. Those teams ship on their own schedules, so a coordinated same-day update across all of them is not possible. The platform team also cannot tell which clients still use the old name. Changing the version number and publishing release notes did not help. What should the release process have done?
Correct answer: D — Publish the new name and keep the old one as a deprecated alias for a stated window, checking old-name call volume before removing it.
- A. A major version number only labels the break. The old name is still gone from the server, so clients with older prompts, few-shot examples or cached tool lists keep calling it and keep getting unknown-tool errors.
- B. This only repairs the one application the team controls. Other client apps pinned to older prompts, cached tool lists and sessions already in flight still call the removed name, and the two deploys cannot land at the same instant.
- C. Name similarity is a guess, so an unknown name can be routed to a different tool with different side effects and run with arguments meant for another schema. It executes the wrong action instead of managing the migration.
- D. Correct: serving both names for a stated window lets clients with older prompts and cached tool lists keep working while they migrate. Old-name call volume shows when removal is safe.
3.Protocol versions, stateless requests and gateways
The protocol has versions of its own, and the 2026-07-28 revision changed how connections work. Revisions from 2025-11-25 and earlier open a session with an initialize handshake. Modern revisions instead send the protocol version, client identity and capabilities as _meta on every request. A dual-era implementation supports both. The matrix below shows which pairings keep working while a fleet moves from one era to the other.
| Client | Server | Outcome |
|---|---|---|
| Modern | Modern | Works; a version mismatch returns UnsupportedProtocolVersionError and the client retries with a version both sides support |
| Modern | Legacy | Fails; on stdio the client should send server/discover first so it fails deterministically |
| Dual-era | Legacy | Works; the client falls back to initialize |
| Legacy | Modern | Fails; legacy clients have no fall-forward mechanism |
| Legacy | Dual-era | Works; the server answers initialize under the legacy revision |
Run the server dual-era until no legacy clients remain. A legacy client has no way to move up to the modern revision, so a server that only speaks modern locks those clients out. A modern client that asks for a version the server lacks gets a structured error listing the versions the server does support, and the client retries with one of them.
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32022,
"message": "Unsupported protocol version",
"data": {
"supported": ["2026-07-28", "2025-11-25"],
"requested": "1900-01-01"
}
}
}Statelessness changes what a rolling deploy breaks. Under the modern Streamable HTTP transport there are no protocol-level sessions. Each request is a separate POST that the server handles statelessly, and the server ignores any Mcp-Session-Id header without issuing or echoing one. Any replica behind the load balancer can therefore serve any request. 'Session not found' errors in the middle of a task, which happen when a replica holding a legacy session is replaced, have nothing to attach to once clients and servers both speak the modern revision.
Modern requests also copy routing facts into HTTP headers. Every request carries Mcp-Method. A tools/call also carries Mcp-Name, and each schema property annotated with x-mcp-header produces an Mcp-Param-{Name} header, so a proxy can see the method and tool name without parsing the body. The server must check that these headers match the body and reject a mismatch with error -32020 HeaderMismatch. Any gateway that rewrites the body must update the headers to match. Gateways can break OAuth too. A gateway that demands its own header blocks the browser sign-in, because the browser does not send that header. In Claude Code, keep Authorization out of the configured headers so the OAuth sign-in supplies it. Pass the proxy's header under its own name.
Checkpoint 7 of 8· Match them up
While a fleet moves to the 2026-07-28 revision, match each client–server pairing to what happens when they connect.
Tap a term, then the definition that fits it.
Only the dual-era side can bridge the two eras, and legacy clients cannot move forward. That is why the server must stay dual-era until no legacy clients remain. Two modern peers recover from a version mismatch by retrying with one of the versions listed in the UnsupportedProtocolVersionError.
“Legacy clients have no fall-forward mechanism.”Source: modelcontextprotocol.io
4.The same MCP configuration on every machine
Fleet-wide parity means every engineer's Claude Code connects to the same endpoints with the same authentication. Managed configuration does this from a single file instead of relying on each person's own setup. Choose the pattern by how much freedom users should keep:
| Pattern | Effect | Configure |
|---|---|---|
| Fixed deployment | Every user gets the listed servers, and servers users configure themselves don't load | managed-mcp.json with the servers you want |
| Provided servers | Every user gets the listed remote servers and keeps their own | managedMcpServers in managed settings |
| Approved catalog | Users add servers from an approved list; anything else is blocked | allowedMcpServers + allowManagedMcpServersOnly: true |
| Denylist only | Known-bad servers are blocked; everything else is allowed | deniedMcpServers |
Each mechanism has rules that cause surprises during rollouts:
- With
managed-mcp.jsondeployed,claude mcp addfails because the enterprise configuration has exclusive control. Users still authenticate as themselves through OAuth or per-user headers. managedMcpServersentries must use anhttps://URL, and${VAR}references in them are not expanded.- Changes to
managedMcpServersreach running sessions. A newly added server connects without a restart. A removed server disconnects from interactive sessions, but aclaude -prun keeps it until the run ends.
Run claude mcp list after rollout to check parity. One drift source is easy to miss: the same server name defined in two scopes with different endpoints. Claude Code warns about the conflict, and because OAuth sign-ins are stored per endpoint, users must sign in separately in each project.
Checkpoint 8 of 8· Match them up
Your platform team is setting up Claude Code for the whole company. Match each requirement to the managed configuration that meets it.
Tap a term, then the definition that fits it.
managed-mcp.json takes exclusive control, so servers users configure themselves do not load. managedMcpServers adds the company's servers alongside the user's own. An allowlist with allowManagedMcpServersOnly creates an approved catalog, and a denylist alone blocks only the servers it names.
“Provided servers | Every user gets the remote servers you list and keeps their own | managedMcpServers in managed settings”Source: code.claude.com
Sources
(8)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Implementations using an STDIO transport SHOULD NOT follow this specification, and instead retrieve credentials from the environment.”
↩︎ Per-user OAuth for a shared remote server“MCP servers MUST implement OAuth 2.0 Protected Resource Metadata (RFC9728).”
↩︎ Per-user OAuth for a shared remote server“Access tokens MUST NOT be included in the URI query string”
↩︎ Per-user OAuth for a shared remote server“Retry the original request with the new authorization no more than a few times and treat this as a permanent authorization failure”
↩︎ Per-user OAuth for a shared remote server“Additive - Extensions do not modify or break core protocol functionality; they add new capabilities while preserving core protocol behavior”
↩︎ Key concept“MUST identify the MCP server that the client intends to use the token with.”
↩︎ Exam trap 2 - 2.
“Receive notifications/tools/list_changed when tools change”
↩︎ Renaming and removing tools without stranding agents - 3.
“Protocol Errors: Standard JSON-RPC errors for issues like: Unknown tools Invalid arguments Server errors”
↩︎ Renaming and removing tools without stranding agents“Tool Execution Errors: Reported in tool results with isError: true”
↩︎ Renaming and removing tools without stranding agents - 4.
“Deprecated: The model is still functional but no longer recommended. Anthropic provides a recommended replacement and assigns a retirement date.”
↩︎ Renaming and removing tools without stranding agents - 5.
“A request carrying modern per-request _meta is served statelessly according to this revision.”
↩︎ Protocol versions, stateless requests and gateways“Legacy clients have no fall-forward mechanism.”
↩︎ Exam trap 3“Legacy clients have no fall-forward mechanism.”
↩︎ Checkpoint - 6.https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-httpOfficial docs
“An Mcp-Session-Id header on a request: ignore it, and do not mint or echo session IDs.”
↩︎ Protocol versions, stateless requests and gateways“The HTTP headers do not match the corresponding values in the request body, or required headers are missing/malformed.”
↩︎ Protocol versions, stateless requests and gateways“Long-lived change notifications (such as list changes and resource updates) are delivered on the response stream of a subscriptions/listen request.”
↩︎ Exam trap 1“Long-lived change notifications (such as list changes and resource updates) are delivered on the response stream of a subscriptions/listen request.”
↩︎ Checkpoint - 7.https://code.claude.com/docs/en/mcpOfficial docs
“An authorization server on another origin: if a gateway in front of that server requires the header too, sign-in fails there.”
↩︎ Protocol versions, stateless requests and gateways“keep Authorization out of the configured headers, then sign in with claude mcp login <name> in your shell.”
↩︎ Protocol versions, stateless requests and gateways“Claude Code stores OAuth sign-ins per endpoint”
↩︎ The same MCP configuration on every machine - 8.https://code.claude.com/docs/en/managed-mcpOfficial docs
“OAuth or per-user headers so each user authenticates as themselves.”
↩︎ The same MCP configuration on every machine“url is an https:// URL. Claude Code refuses a plain http:// URL, including one that points at localhost.”
↩︎ The same MCP configuration on every machine“Add a server: Claude Code connects it when the updated settings arrive, without a restart.”
↩︎ The same MCP configuration on every machine“A non-interactive (-p) run keeps it until it ends.”
↩︎ The same MCP configuration on every machine“OAuth or per-user headers so each user authenticates as themselves.”
↩︎ Checkpoint“Provided servers | Every user gets the remote servers you list and keeps their own | managedMcpServers in managed settings”
↩︎ Checkpoint