Designing for Many Clients

The same MCP server will be listed, described, approved, cached and truncated differently by every host that connects to it. None of those differences is visible from the server. Part V’s rule: build to the protocol, know each host’s capability floor, and back every safety claim on the server, because no host is obliged to honour it. A server built that way survives a new host without a code change. A server built around one host’s behaviour breaks quietly in the next one.

This page holds the advice that applies to every host. The four chapters after it cover only what is different: Claude’s surfaces (Chapter 14), OpenAI’s (Chapter 15), developer tools (Chapter 16), and building your own client (Chapter 17). Those four are the scope of this part. A host with no chapter here gets the rules on this page, and its own MCP documentation for the rest. The running example is the notes server from Chapter 5, taken remote at https://notes.example.com/mcp in Chapter 7. You will see the same server configured in each host.

The Capability Floor Decides What Your Server Can Rely On

Tools work everywhere. Everything else depends on the host, and on which surface of that host the user happens to be on.

“Check” means the vendor’s MCP page did not say either way on the date above. The table will drift. The official extension client matrix tracks MCP Apps and the auth extensions, and each vendor’s MCP page is the source for core features. Re-check both before a release, not before every design decision.

The design consequence is fixed even when the cells move. Everything the model needs must be reachable through a tool. Resources and prompts improve the experience on hosts that show them, and vanish without an error on hosts that don’t. A notes://summary resource is a convenience. The search_notes tool is the contract. That is the rule from Chapter 6 (D5), and Part V is where it pays for itself: a user who connects notes through the Connector API or the Responses API gets tools and nothing else.

One Catalog Threshold for Every Host

Past about 20 tools in a session, measure tool-selection accuracy with a scenario eval (Chapter 12) instead of assuming it holds. Past about 40, use the host’s tool search or deferred loading, or split the server. Chapter 13 prices the catalog. The count that matters is the session’s total across every connected server, not your server’s own count. Three servers with 15 tools each put a user at 45, past the split line, even though no single server looks large.

Each host offers a different lever for staying under the line: allowed_tools and defer_loading on OpenAI, mcp_toolset allowlists and tool search on Claude’s API, per-tool toggles and profiles in editors. The chapters show each lever. The threshold does not change between them.

Annotations Are a Shared Contract That Only the Server Can Back

Every host reads readOnlyHint and destructiveHint, and every host uses them differently. Claude’s directory review requires them and uses them for auto-permission (Chapter 14). OpenAI developers turn them into require_approval maps (Chapter 15). Editors in auto-approve mode may skip the prompt entirely (Chapter 16). A custom client may trust them only from servers on its allowlist (Chapter 17).

So write annotations for the strictest reader and enforce them for the laxest. Chapter 6 gives the rule: annotations are hints, and a hint that lies is worse than none. In practice, delete_note should carry destructiveHint: true and refuse to run without a confirm: true argument, and it should delete one note by id, never everything matching a tag or query. A host that ignores the hint still hits the server’s own checks.

Test One Server Against Many Hosts

A server that passes MCP Inspector has passed the protocol. It has not passed the hosts. Before each release that changes a tool name, description, schema or annotation, run this plan against the notes server:

1. Contract tests in CI. tools/list output is snapshotted, and any change to a name, schema or annotation fails the build until someone approves it (Chapter 12). Hosts cache tool lists (Chapter 15) or pin them (Chapter 14), so an unreviewed change reaches users on different days on different hosts.
2. The tools-only pass. Connect through one tools-only surface (the Connector API or the Responses API) and run the three core tasks: create a note, find it, delete it. If a task needs a resource or prompt to succeed, the server fails.
3. The approval pass. In one host that prompts per call and one that auto-approves, confirm that delete_note is gated both times. In the auto-approve host, the gate must be the server’s confirm argument.
4. The size pass. Search a corpus large enough to return a long list and check the result stays under the smallest host limit you support. Claude Code warns at 10,000 tokens of tool output (Chapter 14), which makes a practical ceiling.
5. The auth pass. Sign in from two hosts. Each completes OAuth on its own, and each token the server accepts has https://notes.example.com/mcp as its audience (Chapter 19). A token minted for any other resource gets a 401, from every host.

Five passes, two hosts minimum. The plan catches the bug no single-host test can: the change that is correct in the protocol and wrong in one host.

What One Server Across Three Hosts Looks Like

The server I run for Atelier customers is one endpoint, https://mcp.elier.ai/mcp, that customers reach from ChatGPT, Codex and Claude to edit their own live websites. Every host gets the same tools and the same annotations, built by two helpers so that no tool ships without a read or write hint. The differences live at the edges. Discovery is left unauthenticated so ChatGPT and Claude can list tools before sign-in, and each tool advertises its required scopes. Each host signs in differently: codex mcp login, claude mcp add --transport http, a ChatGPT app with its own callback URL. And one tool, generate_image, is off by default because AI image generation disqualifies a server from Anthropic’s Connectors Directory. That flag is the only host-specific branch in the tool surface. Everything else is the protocol.

What Comes Next

The rule for the rest of this part is to state what each host changes and nothing else. Chapter 14 starts with Anthropic’s surfaces, where the question is which behaviours are MCP and which are Claude.