CertSafari
    Anthropic Claude Certified Developer – Professional (CCDV-P)· Lessons

    Domain 2 · Lesson 7/25

    Remote MCP servers in production: auth, tool changes and protocol versions

    Production MCP and Change Management

    16 min read
    5% of exam
    8 sources
    Published 19 Nov 2026
    Docs as of 18 Nov 2026

    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.
    A per-operation scope challenge: the token is valid, but this operation needs files:writehttp
    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"

    Checkpoint 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?

    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?

    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.

    A tool execution error is a normal result the model reads, flagged with isErrorjson
    {
      "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?

    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)

    0 of 2 selected

    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?

    Sources234

    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 and server pairings during the move to the modern revision
    ClientServerOutcome
    ModernModernWorks; a version mismatch returns UnsupportedProtocolVersionError and the client retries with a version both sides support
    ModernLegacyFails; on stdio the client should send server/discover first so it fails deterministically
    Dual-eraLegacyWorks; the client falls back to initialize
    LegacyModernFails; legacy clients have no fall-forward mechanism
    LegacyDual-eraWorks; 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.

    A modern server tells the client which versions it supportsjson
    {
      "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.

    Sources567

    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:

    Managed MCP patterns in Claude Code
    PatternEffectConfigure
    Fixed deploymentEvery user gets the listed servers, and servers users configure themselves don't loadmanaged-mcp.json with the servers you want
    Provided serversEvery user gets the listed remote servers and keeps their ownmanagedMcpServers in managed settings
    Approved catalogUsers add servers from an approved list; anything else is blockedallowedMcpServers + allowManagedMcpServersOnly: true
    Denylist onlyKnown-bad servers are blocked; everything else is alloweddeniedMcpServers

    Each mechanism has rules that cause surprises during rollouts:

    • With managed-mcp.json deployed, claude mcp add fails because the enterprise configuration has exclusive control. Users still authenticate as themselves through OAuth or per-user headers.
    • managedMcpServers entries must use an https:// URL, and ${VAR} references in them are not expanded.
    • Changes to managedMcpServers reach running sessions. A newly added server connects without a restart. A removed server disconnects from interactive sessions, but a claude -p run 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.

    Sources87

    Sources

    (8)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 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. 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
    3. 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
    4. 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
    5. 6.
      “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
    6. 7.
      “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
    7. 8.
      “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

    Continue to part 2 of 2

    Model migration and prompt versioning with progressive rollout

    Spotted a mistake, or was something unclear? Tell us.