Community-maintained FDE reference. Not an official Vercel or Anthropic project. About this project
Docs for Architects
Designing systems and choosing patterns. 34 pages tagged architect. See all audiences.
Overview 1
Getting started 1
Internals 8
- Internals Reading order for the internals section: roles, capability primitives, transports, serverless sessions, the 2026-07-28 revision, an annotated message trace, and tasks.
- MCP internals overview How the host, client, and server roles fit together, what each one owns, and why the 2026-07-28 revision makes every MCP request self-contained.
- Capability primitives The MCP server primitives (tools, resources, prompts) and auxiliary ones (sampling, elicitation, tasks, logging), with the control model and hosting rules for each on Vercel.
- Transports Streamable HTTP and stdio in depth: one POST per request, streaming responses, protocol version headers, origin checks, and what a Vercel Function can and cannot do with each.
- Serverless sessions What changed when MCP went stateless: no sessions, no initialize handshake, server/discover as the capability probe, and how per-request state maps onto Vercel Functions.
- The 2026-07-28 stateless revision Change log for the 2026-07-28 MCP revision: removed sessions and initialization, server/discover, result types, cache hints, MRTR, and what each change means on Vercel.
- Annotated message trace A complete JSON-RPC exchange over Streamable HTTP, frame by frame: discovery, a tool call, streaming progress, and the final result, annotated for a Vercel Function.
- Tasks (extension) The io.modelcontextprotocol/tasks extension: durable, pollable requests with a CreateTaskResult, status polling, and how to back them with Vercel Queues or Workflows.
Patterns 9
- Patterns Index of the eight MCP design patterns for Vercel (adapter, sidecar, facade, least privilege, trust boundaries, orchestrator, query vs command, async jobs) with their runnable examples.
- Adapter The adapter pattern: a thin MCP server that wraps one untouched backend, with schema-expressed bounds, a scoped read-only credential, and sanitized output, mapped onto Vercel.
- Sidecar The sidecar pattern: run risky work in Vercel Sandbox microVMs with a deny-by-default egress policy, a pinned image, no ambient credentials, and size-capped output.
- Facade The facade pattern: one MCP server fronting many backends behind a namespaced tool surface with centralized routing, error containment, and a secret-free audit log.
- Least Privilege The least privilege pattern: declared per-tool scopes, per-principal tools/list, default-deny authorization from the verified token, bounded inputs, and refuse-to-start credential checks.
- Trust Boundaries The trust boundaries pattern: where host, client, server, and backend trust ends, and how Vercel projects, environments, and Sandbox enforce those boundaries.
- Orchestrator The orchestrator pattern: a host that composes several MCP servers into one namespaced tool layer, routes calls, and gates destructive tools behind fail-closed consent.
- Query vs Command The query vs command pattern: split tools into read-only queries and consent-gated, idempotency-keyed commands, with annotations a host can act on.
- Async Jobs The async jobs pattern: return an opaque handle fast, do the work on Vercel Queues or Workflows, report progress, and make result retrieval idempotent and per-principal.
Security 4
- Security Reading order for the security section: OAuth 2.1 authorization on Vercel, where the principal comes from, and the printable pre-deploy checklist.
- Authorization flows OAuth 2.1 for MCP servers on Vercel: the server as a resource server, RFC 9728 discovery, RFC 8707 audience checks, withMcpAuth, and the token passthrough anti-pattern.
- Where the principal comes from Why the verified access token is the only safe source of a principal, how the examples derive it from AuthInfo, and why identity in tool arguments is never trusted.
- MCP server security checklist A printable pre-deploy security checklist for MCP servers on Vercel: transport, authorization, input and output trust, credentials, deployment protection, and logging.
Client-side 7
- Client-side patterns Reading order for the host and client side of MCP: multi-server composition, consent UX, sampling, elicitation, tool-result rendering, and credential brokering.
- Multi-server composition How a host runs one client per server and merges their capabilities into one namespaced surface, using server/discover as the per-server capability probe.
- Consent UX What a host must show before approving a tool call, why the consent gate is fail-closed, why server annotations are hints, and how MRTR retries pass the same gate.
- Sampling-request handling How a host brokers a server sampling request under 2026-07-28, why sampling is deprecated (SEP-2577), and the human-in-the-loop rules that still apply.
- Elicitation How a host supplies user input mid-request under 2026-07-28: input_required results, retries with inputResponses, form and URL modes, and the never-elicit-secrets rule.
- Tool-result rendering Treating tool results as untrusted data: dispatch on resultType, sanitize what the user sees, re-inject output with provenance, and prefer validated structured output.
- Credential brokering How a host holds the secrets and hands each server a narrowly scoped, short-lived credential, keeping client auth tokens and upstream credentials separate.