MCP Server Architecture Patterns: 5 Designs and 4 Anti‑Patterns Uncovered

Methodology

Researchers examined 15 independent MCP servers (5 production from ANSYR voice‑AI platform, 10 public) using a two‑stage coding process: open coding to label recurring structural decisions, then pattern coding to group decisions that appear in at least two servers and solve a problem without an existing solution. Validation on 54 held‑out servers by two LLM reviewers (Claude Haiku 4.5 and Claude Sonnet 4) yielded Cohen’s κ = 0.76.

Architecture Patterns

Pattern 1 – Resource Gateway

Scenario : Agent needs read‑only access to one or more back‑end systems.

Problem : Expose data to the LLM while preventing prompt‑injection and keeping the interface stable across schema changes.

Solution : Server acts as a gateway, exposing reads as Resources and parameterised queries as Tools . A sanitisation layer strips or escapes potentially malicious content before returning it.

server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
  const doc = await db.collection('documents').findOne({ _id: extractId(req) });
  // Sanitize before LLM sees the content
  return { contents: [{ uri: req.params.uri, text: sanitize(JSON.stringify(doc)) }] };
});

Pros : Single entry point for access control; schema changes do not break the LLM side; prompt‑injection risk is confined.

Cons : Extra network hop per read; complex joins/aggregations are awkward to express as Resources.

Pattern 2 – Tool Orchestrator

Scenario : Agent must perform a multi‑system workflow (e.g., create ticket, notify owner, post message).

Problem : Expose the workflow without requiring the LLM to understand each API, maintain intermediate state, or handle partial failures.

Solution : Encapsulate the entire workflow as a single “composite tool”; all sub‑calls happen inside the server and only a summary result is returned.

Pros : Reduces LLM reasoning load; provides transaction‑like semantics; LLM stays oblivious to low‑level API details.

Cons : Reduced reuse of sub‑tools; failure handling is the server’s responsibility; workflow logic lives in both code and documentation, risking drift.

Pattern 3 – Stateful Session Server

Scenario : Multi‑turn interactions where later calls depend on earlier state (open file, ongoing DB transaction, authenticated user).

Problem : MCP tools are stateless by default; how to persist state across calls?

Solution : Generate a session ID at connection time, return it with every tool response, and store per‑session context in memory (or Redis for distributed deployments). Idle sessions are reclaimed after a timeout.

Pros : Natural multi‑turn workflows; avoids repeated data transfer; enables transaction‑like semantics.

Cons : Potential memory leaks if sessions are not reclaimed; distributed deployments need external session storage; LLM must reliably return the session ID, which the protocol does not guarantee.

Pattern 4 – Proxy Aggregator

Scenario : Agent needs capabilities from multiple upstream MCP servers but the client can maintain only a limited number of connections, or the operator wants unified authentication and audit logging.

Problem : Consolidate many upstream servers into a single entry point without losing identity, versioning, or fault isolation.

Solution : Deploy a proxy server that connects to N upstream servers, prefixes tool names with namespaces to avoid collisions, and routes each call to the appropriate upstream. Two variants:

Static‑merge : Expose the union of all upstream tools at once.

Scoped (on‑demand) filtering : Expose only the subset of tools relevant to the current task.

Pros : Simplifies client configuration; centralises authentication and audit; supports large‑scale tool discovery.

Cons : Introduces a single point of failure; extra network hop per call; namespace conflicts need governance; upstream failures propagate; scoped variant requires fast, accurate filtering.

Pattern 5 – Domain‑Specific Adapter

Scenario : Existing APIs are useful for humans but unfriendly to LLMs (opaque IDs, complex auth, heavy post‑processing).

Problem : Translate a complex, low‑level API into a form that LLMs can use accurately without re‑implementing business logic.

Solution : Build a semantic adapter layer that provides clear tool descriptions, input normalisation (e.g., natural‑language dates), output enrichment (e.g., resolve IDs to names), and error translation (API error codes to human‑readable messages).

Pros : Precise descriptions boost tool‑selection accuracy; isolates API complexity; adapter can absorb API version changes.

Cons : Adapter must be updated whenever the underlying API changes; if the API is already LLM‑friendly, the adapter may be unnecessary overhead.

Anti‑Patterns

God Tool : A single tool with a huge, generic schema (e.g., do_anything(action:string, params:object)) forces the LLM to guess the action, collapsing selection accuracy. Remedy: split into narrowly scoped tools.

Un‑sanitised Resources : Returning raw user‑generated content can be interpreted as instructions. Always sanitise external content before exposing it.

Synchronous Long‑Running Tasks : Performing heavy work synchronously causes client timeouts. Return a task ID and expose a poll_job(id) tool for asynchronous polling.

Missing or Vague Tool Descriptions : Tools without clear descriptions leave the LLM unable to select them correctly. Descriptions must state purpose, when to use, and expected return.

Empirical Findings

Transmission Latency

End‑to‑end latency of stdio vs. streamable‑http on the same machine (100 calls each) showed sub‑millisecond protocol overhead. Modeling cross‑region scenarios indicated network RTT (~30 ms p50) dominates; therefore architecture decisions should focus on server placement and proxy hops rather than transport choice.

Tool Count vs. Selection Accuracy

Production telemetry from ANSYR Q1 2025 was bucketed by tool count (1, 3, 5, 10, 15, 20, 30, 50) and tool‑selection accuracy measured for Claude Haiku 4.5 and Claude Sonnet 4.

Haiku 4.5: 91 % accuracy at 10 tools, dropping to 87 % at 15 tools – the 90 % threshold lies between 10‑15 tools.

Sonnet 4: ≥90 % accuracy up to 20 tools; accuracy falls after 30 tools.

Guideline: keep the number of exposed tools per context under 10‑15. When a server approaches this limit, switch to the scoped Proxy Aggregator variant to filter tools on demand.

Cross‑Cutting Concerns

Authentication : Perform auth at the transport layer (e.g., Bearer Token support in streamable‑http), scope tokens per tool set, and log caller identity.

Error handling : Return structured error objects instead of raw exceptions so the LLM can decide whether to retry or surface the error.

Version management : Include a version field in the initialize response; bump major version for breaking schema changes and keep old schemas alive during migration.

Observability : Log tool name, input hash, latency, output size, and error code for each call to aid troubleshooting of LLM behaviour.

Decision Checklist

Read‑only backend data → use Resource Gateway with sanitisation.

Cross‑system multi‑step workflow → encapsulate as Tool Orchestrator.

Stateful interactions needed → adopt Stateful Session Server with proper session reclamation.

Aggregating upstream servers → prefer scoped Proxy Aggregator over static merging.

Expose ≤ 10‑15 tools per context.

Treat tool descriptions as core engineering artifacts; review them like code.

Relation to Language Server Protocol

Both MCP and LSP aim to decouple the host (LLM client or editor) from capability providers (MCP server or language server). Success depends on establishing a shared vocabulary of architecture patterns to guide developers.

Conclusion

The five patterns and four anti‑patterns constitute a design language for building MCP servers that are safe and performant for LLM‑driven agents. Empirical evidence of a “10‑15 tool” accuracy threshold warns against indiscriminately exposing all capabilities, and the checklist helps teams avoid common pitfalls.