Consuming servers

Read these first

• Transports

What you will know

• Discover, configure, and connect a third-party server

  Verify the endpoint, transport, credentials, advertised capabilities, and environment-specific configuration rather than assuming a working local setup transfers to production.

• Handle a server whose schema changed under you

  Exercise removed fields, renamed tools, and tightened argument validation so the client fails safely instead of sending invalid calls or misreading results.

• Pin a version and explain why

  Choose an immutable release or digest with an explicit update policy, balancing reproducibility against the need to receive fixes and security patches.

• Diagnose a breakage as a server-side change rather than your own bug

  Compare the failing initialization or tool contract with a known-good response and server revision before changing client logic or prompts.

• Decide what happens to the agent when a server is unavailable

  Set bounded timeouts and an explicit fallback such as omission, cached data, or a hard failure, while preventing fabricated results from a missing tool.

Chapters

1. 1

   Adopting a server from a registry

   A registry entry gives you a name, a publisher and usually an install command; it does not establish that the publisher is who you assume, that the artefact behind the listing is the one described, or that the endpoint it advertises is the one production will call. Adopting a listed server means confirming those three by hand, attaching a credential minted for the job, and connecting once to record the capability set and tool list the server actually serves.

   Read chapter
2. 2

   Local and hosted server builds

   You develop against a vendor's server launched locally over stdio with your own API key in the process environment; production points at their hosted HTTPS endpoint. Close to none of that carries across: the hosted build can advertise a different capability set and tool list, credentials become a request-time authorization scheme with its own expiry, and failures stop being a crashed child and start being timeouts and drops. This chapter sets out what to re-verify per environment, and why parity is not available for a server somebody else operates.

   Read chapter
3. 3

   Pinning a server version

   Four months of npx -y vendor-server@latest working is not evidence it will work tomorrow, and the morning every agent run fails at tool-call time with no commits in your repository is the bill arriving. This chapter covers immutable pins — an exact version with a lockfile, a digest for a container — and the half everyone omits: who reviews a release, on what cadence you take it, and which security fixes may jump that queue.

   Read chapter
4. 4

   Detecting contract drift

   Pinning freezes an artefact, which only helps for servers you launch yourself. A vendor's hosted endpoint has no artefact to pin, a container tag can point at a new image after any restart, and both look pinned on paper. This chapter records initialize and tools/list from a scheduled job that connects exactly the way production does, diffs it against a committed snapshot, and says honestly what detection buys that prevention would have.

   Read chapter
5. 5

   Diagnosing a failure with no deploy

   A tool call that worked yesterday now complains about an unexpected argument, and nobody has committed anything. The instinct is to open the client's argument builder; the cheaper first move is to pull the server's current tools/list, diff it against the snapshot from when this last worked, and record which build answered. This chapter also orders five servers by how easily they move — two look pinned and are not — and reads what a 20% failure rate says on its own.

   Read chapter
6. 6

   Validating tool arguments and results

   When a server tightens limit from any positive integer to a maximum of 100 and your client has always sent 500, the failure arrives mid-run from the far side of the wire. The behaviour to build is a client that validates arguments against the server's advertised schema before sending, and fails loudly when they no longer fit. Renamed tools and tightened validation are caught the same way, but drift on the inbound side breaks nothing on the wire and needs its own guard.

   Read chapter
7. 7

   Agent memory and unavailable tools

   Bounded timeouts and a stated fallback per server — omission, cached data, or hard failure — replace the reflex of wrapping every dependency in the same retry and letting the model decide from the error text. The behaviour to design out entirely is agent memory answering a pricing question as though the tool had returned. Work out why inventory, pricing and internal search deserve three different policies, and when a cached price is acceptable.

   Read chapter