Client Best Practices changeddocs/draft/develop/clients/client-best-practices
Upstream edited this page at 28 Jul 2026 15:42 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 24 Oct 2026 11:07 UTC.
Upstream edited
Recorded here
Lines+5added
Lines−5removed
From line
123
where the diff opens
First seen
26 Aug 2026
this site's first read of the page
Recorded edits5to this page, all time
The whole hunk
from line 123, old and new numbered
/
from line 123
123123 Host-->>Model: Server disconnected, context freed
124124```
125125
126This works especially well for general-purpose agents, where the user's intent isn't known upfront. The agent starts with a minimal set of always-on servers and connects others as needed. Combined with [agent skills](/docs/draft/develop/build-with-agent-skills.md), a skill file can declare which MCP servers it needs, and the host connects them only when that skill is invoked.
126This works especially well for general-purpose agents, where the user's intent isn't known upfront. The agent starts with a minimal set of always-on servers and connects others as needed. Combined with [agent skills](https://modelcontextprotocol.io/docs/draft/develop/build-with-agent-skills.md), a skill file can declare which MCP servers it needs, and the host connects them only when that skill is invoked.
127127
128128### Implementation Guidelines
129129
from line 140
140140
141141Each list result (such as `tools/list`), as well as each `server/discover` and
142142`resources/read` result, carries `ttlMs` and `cacheScope` hints. Follow them as defined in the
143specification's [caching utility](/specification/draft/server/utilities/caching.md). In particular,
143specification's [caching utility](https://modelcontextprotocol.io/specification/draft/server/utilities/caching.md). In particular,
144144treat a cached list as stale once a `list_changed` notification arrives, even before its TTL
145145expires.
146146
from line 198
198198}
199199```
200200
201MCP Servers can provide an optional [`outputSchema`](/specification/draft/server/tools#output-schema) for each tool. When an output schema is present, the host can produce precise return types (like `LogEntry` above).
201MCP Servers can provide an optional [`outputSchema`](https://modelcontextprotocol.io/specification/draft/server/tools#output-schema) for each tool. When an output schema is present, the host can produce precise return types (like `LogEntry` above).
202202
203203When an output schema is absent, prefer the simple path:
204204
from line 280
280280
281281Programmatic tool calling introduces a code execution surface that requires careful sandboxing:
282282
283* **Per-call authorization**: The broker is still the MCP host for spec purposes. Apply the same human-in-the-loop confirmation policy to sandbox-originated calls that you apply to direct calls (see [Tools: Security](/specification/draft/server/tools.md#security-considerations)). Approving the script does not grant blanket approval for every tool call it makes at runtime; hosts may grant categorical approval (for example, "allow `ticketing_createIssue` for this script run") rather than prompting per iteration, but the broker must still evaluate each call against that grant.
283* **Per-call authorization**: The broker is still the MCP host for spec purposes. Apply the same human-in-the-loop confirmation policy to sandbox-originated calls that you apply to direct calls (see [Tools: Security](https://modelcontextprotocol.io/specification/draft/server/tools.md#security-considerations)). Approving the script does not grant blanket approval for every tool call it makes at runtime; hosts may grant categorical approval (for example, "allow `ticketing_createIssue` for this script run") rather than prompting per iteration, but the broker must still evaluate each call against that grant.
284284* **Cross-server data flow**: Tool results from one server are untrusted input to another. The broker should apply the same input-review policy to brokered calls as to direct ones; output truncation alone does not prevent exfiltration.
285285* **Network isolation**: The sandbox should have no direct network access. All external communication flows through the host broker, which enforces authorization and access control.
286286* **No credential exposure**: API keys and tokens are held by the host. The generated code calls typed functions; the host adds authentication when forwarding to servers.
from line 290
290290### Error Handling
291291
292292MCP tool errors arrive as a successful response with
293[`isError: true`](/specification/draft/server/tools#error-handling) rather than a transport
293[`isError: true`](https://modelcontextprotocol.io/specification/draft/server/tools#error-handling) rather than a transport
294294failure. Generated wrappers should convert this into a thrown exception so model-authored code
295295can use `try`/`catch`. If an uncaught error terminates the script, surface it as the script's
296296result so the model can self-correct; the model is responsible for reporting any partial side
No line in this hunk matches that.