# vercel-mcp-reference

> A practical reference for designing, securing, testing, and deploying Model Context Protocol (MCP) servers on Vercel: opinionated docs backed by small runnable TypeScript examples, targeting MCP spec revision 2026-07-28. It is community-maintained by forward deployed engineers (FDE) and is an independent project: not an official Vercel or Anthropic project, and not affiliated with, endorsed by, or published by either company.

The reference sits between the MCP specification (what is required) and tutorials (what to type): it explains how serverless changes the shape of an MCP server (Streamable HTTP, no resident process, cross-call state in explicit handles, authorization on every deployed server) and gives a reusable pattern, a security checklist, and a runnable example for each situation. Every page declares the MCP spec revision it was verified against, its audience, and its last review date, and ends with a bibliography of primary sources (the MCP specification and vercel.com/docs).

Each page is also served as plain markdown at its canonical URL with `.md` appended in place of the trailing slash (for example https://vercel-mcp-reference.vercel.app/patterns/adapter.md; the site root is https://vercel-mcp-reference.vercel.app/index.md). https://vercel-mcp-reference.vercel.app/llms-full.txt concatenates every page in reading order. Documentation is licensed CC-BY-4.0; the example code is MIT.

## Getting started

- [Overview](https://vercel-mcp-reference.vercel.app/): Map of the vercel-mcp-reference documentation: sections, reading paths per audience, page conventions, and the community-maintained (FDE) status of the project.
- [Getting started with MCP on Vercel](https://vercel-mcp-reference.vercel.app/getting-started/): The MCP mental model (host, client, server), the three primitives, the stateless request lifecycle, and a 10-minute path from clone to a deployed server on Vercel.

## Internals

- [Internals](https://vercel-mcp-reference.vercel.app/internals/): Reading order for the internals section: roles, capability primitives, transports, serverless sessions, the 2026-07-28 revision, an annotated message trace, and tasks.
- [Annotated message trace](https://vercel-mcp-reference.vercel.app/internals/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.
- [MCP internals overview](https://vercel-mcp-reference.vercel.app/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](https://vercel-mcp-reference.vercel.app/internals/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.
- [Serverless sessions](https://vercel-mcp-reference.vercel.app/internals/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](https://vercel-mcp-reference.vercel.app/internals/spec-2026-07-28/): 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.
- [Tasks (extension)](https://vercel-mcp-reference.vercel.app/internals/tasks/): The io.modelcontextprotocol/tasks extension: durable, pollable requests with a CreateTaskResult, status polling, and how to back them with Vercel Queues or Workflows.
- [Transports](https://vercel-mcp-reference.vercel.app/internals/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.

## Patterns

- [Patterns](https://vercel-mcp-reference.vercel.app/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](https://vercel-mcp-reference.vercel.app/patterns/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.
- [Async Jobs](https://vercel-mcp-reference.vercel.app/patterns/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.
- [Facade](https://vercel-mcp-reference.vercel.app/patterns/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](https://vercel-mcp-reference.vercel.app/patterns/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.
- [Orchestrator](https://vercel-mcp-reference.vercel.app/patterns/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](https://vercel-mcp-reference.vercel.app/patterns/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.
- [Sidecar](https://vercel-mcp-reference.vercel.app/patterns/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.
- [Trust Boundaries](https://vercel-mcp-reference.vercel.app/patterns/trust-boundaries/): The trust boundaries pattern: where host, client, server, and backend trust ends, and how Vercel projects, environments, and Sandbox enforce those boundaries.

## Security

- [Security](https://vercel-mcp-reference.vercel.app/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](https://vercel-mcp-reference.vercel.app/security/authorization/): 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.
- [MCP server security checklist](https://vercel-mcp-reference.vercel.app/security/checklist/): A printable pre-deploy security checklist for MCP servers on Vercel: transport, authorization, input and output trust, credentials, deployment protection, and logging.
- [Where the principal comes from](https://vercel-mcp-reference.vercel.app/security/identity-and-principals/): 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.

## Client-side

- [Client-side patterns](https://vercel-mcp-reference.vercel.app/client-side/): Reading order for the host and client side of MCP: multi-server composition, consent UX, sampling, elicitation, tool-result rendering, and credential brokering.
- [Consent UX](https://vercel-mcp-reference.vercel.app/client-side/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.
- [Credential brokering](https://vercel-mcp-reference.vercel.app/client-side/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.
- [Elicitation](https://vercel-mcp-reference.vercel.app/client-side/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.
- [Multi-server composition](https://vercel-mcp-reference.vercel.app/client-side/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.
- [Sampling-request handling](https://vercel-mcp-reference.vercel.app/client-side/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.
- [Tool-result rendering](https://vercel-mcp-reference.vercel.app/client-side/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.

## Testing

- [Testing patterns](https://vercel-mcp-reference.vercel.app/testing/): Testing MCP servers with vitest and InMemoryTransport, HTTP-level route tests, MCP Inspector, and the rule of asserting the negatives, with the legacy-only in-memory caveat.

## Observability

- [Observability patterns](https://vercel-mcp-reference.vercel.app/observability/): Structured logging, tracing, and metrics for MCP tool invocations on Vercel, with correlation ids, redaction rules, and log drains.

## Deployment

- [Deploying MCP servers on Vercel](https://vercel-mcp-reference.vercel.app/deployment/): Vercel deployment mechanics for MCP servers: vercel.json anatomy, environments, Deployment Protection, rollbacks, log drains, and cost shape.

## Examples

- [Examples](https://vercel-mcp-reference.vercel.app/examples/): Narrative index of the thirteen runnable TypeScript examples: which pattern each teaches, the pinned stack, the wire status, and how to run and deploy them.

## Glossary

- [Glossary](https://vercel-mcp-reference.vercel.app/glossary/): Plain-language definitions of the MCP and Vercel terms used across the reference, alphabetized and cross-linked from every page.

## Optional

- [Build-it-yourself prompts](https://vercel-mcp-reference.vercel.app/examples/prompts/): Copy-paste prompts that rebuild each runnable example with an AI coding agent: same stack, same behaviors, same tests.
- [Prompt: async-jobs-server](https://vercel-mcp-reference.vercel.app/examples/prompts/async-jobs-server/): Generation prompt for async-jobs-server: long jobs behind opaque handles with progress, cancellation, per-principal caps, and a private queue consumer route.
- [Prompt: auth-server](https://vercel-mcp-reference.vercel.app/examples/prompts/auth-server/): Generation prompt for auth-server: an OAuth-protected MCP server with RFC 9728 discovery metadata, a pinned resource URL, RFC 8707 audience checks, and a fail-closed verifier.
- [Prompt: db-adapter-server](https://vercel-mcp-reference.vercel.app/examples/prompts/db-adapter-server/): Generation prompt for db-adapter-server: a read-only MCP wrapper around a legacy backend with schema-expressed bounds and sanitized output.
- [Prompt: elicitation-server](https://vercel-mcp-reference.vercel.app/examples/prompts/elicitation-server/): Generation prompt for elicitation-server: a book_meeting tool that pauses mid-call to confirm a bounded topic with the user and handles accept, decline, and cancel.
- [Prompt: facade-server](https://vercel-mcp-reference.vercel.app/examples/prompts/facade-server/): Generation prompt for facade-server: one MCP server fronting two backends with namespaced tools, centralized routing, error containment, and an audit log.
- [Prompt: least-privilege-server](https://vercel-mcp-reference.vercel.app/examples/prompts/least-privilege-server/): Generation prompt for least-privilege-server: declared per-tool scopes, per-principal tools/list, default-deny authorization from the bearer token, and bounded refund inputs.
- [Prompt: minimal-server](https://vercel-mcp-reference.vercel.app/examples/prompts/minimal-server/): Generation prompt for minimal-server: the smallest end-to-end MCP server, one echo tool over Streamable HTTP with an Origin allowlist and in-memory tests.
- [Prompt: orchestrator-host](https://vercel-mcp-reference.vercel.app/examples/prompts/orchestrator-host/): Generation prompt for orchestrator-host: a host that runs one client per server, merges namespaced tools, routes calls, and gates destructive tools behind consent.
- [Prompt: query-command-server](https://vercel-mcp-reference.vercel.app/examples/prompts/query-command-server/): Generation prompt for query-command-server: read-only query tools plus a consent-gated, idempotency-keyed write command with host-actionable annotations.
- [Prompt: resources-server](https://vercel-mcp-reference.vercel.app/examples/prompts/resources-server/): Generation prompt for resources-server: a resources-only MCP server with static resources and resource templates, no tools.
- [Prompt: sampling-server](https://vercel-mcp-reference.vercel.app/examples/prompts/sampling-server/): Generation prompt for sampling-server: a summarize tool that asks the host model for a completion, kept as a deprecated-pattern reference.
- [Prompt: sandbox-isolation-server](https://vercel-mcp-reference.vercel.app/examples/prompts/sandbox-isolation-server/): Generation prompt for sandbox-isolation-server: untrusted commands in a non-persistent Vercel Sandbox microVM behind a frozen egress allowlist and a pinned image.
- [Prompt: secure-tools-server](https://vercel-mcp-reference.vercel.app/examples/prompts/secure-tools-server/): Generation prompt for secure-tools-server: one hardened write tool with input validation, default-deny authorization from the verified bearer token, and an Origin allowlist.
- [Audiences](https://vercel-mcp-reference.vercel.app/audience/): Curated indexes of the same pages by audience, generated from each page's frontmatter.
- [Engineers](https://vercel-mcp-reference.vercel.app/audience/engineer/): Building and integrating MCP servers and clients.
- [Architects](https://vercel-mcp-reference.vercel.app/audience/architect/): Designing systems and choosing patterns.
- [Security](https://vercel-mcp-reference.vercel.app/audience/security/): Threat models, authorization, identity, and trust boundaries.
- [Non-technical](https://vercel-mcp-reference.vercel.app/audience/non-technical/): Conceptual overviews without implementation detail.
- [llms-full.txt](https://vercel-mcp-reference.vercel.app/llms-full.txt): Every page above as one plain-text markdown file, in reading order.