# Overview

Canonical URL: https://vercel-mcp-reference.vercel.app/
Markdown: https://vercel-mcp-reference.vercel.app/index.md
Audience: engineer, architect, security, non-technical. MCP spec version: 2026-07-28. Last reviewed: 2026-08-26. Status: stable.

> **Community-maintained by forward deployed engineers (FDE).** This is an independent reference. It is not an official Vercel or Anthropic project and is not affiliated with, endorsed by, or published by either company. See [About this project](#about-this-project).

Top-level map of the `vercel-mcp-reference` documentation: a practical reference for designing, securing, testing, and deploying Model Context Protocol (MCP) servers on Vercel. Every page declares its target MCP spec version, audience, and last-reviewed date in its frontmatter, so you always know what a page was checked against and when.

## Sections

| Section | What's in it | Status |
|---|---|---|
| [`getting-started/`](https://vercel-mcp-reference.vercel.app/getting-started/) | The mental model (host, client, server), the three primitives, the connection lifecycle, and a 10-minute path from clone to a deployed server | Stable |
| [`internals/`](https://vercel-mcp-reference.vercel.app/internals/) | How MCP works under the hood: roles, primitives, transports, how the 2026-07-28 revision's native statelessness meets function invocations, an annotated message trace, tasks | Stable (the [2026-07-28 revision page](https://vercel-mcp-reference.vercel.app/internals/spec-2026-07-28/) is the change log for the revision these docs now target) |
| [`patterns/`](https://vercel-mcp-reference.vercel.app/patterns/) | Eight reusable design patterns (adapter, sidecar, facade, orchestrator, query-vs-command, async jobs, least privilege, trust boundaries), each with a Vercel mapping and a runnable example | Stable |
| [`security/`](https://vercel-mcp-reference.vercel.app/security/) | OAuth 2.1 authorization on Vercel, identity and principals, and the printable pre-deploy [checklist](https://vercel-mcp-reference.vercel.app/security/checklist/) | Stable |
| [`client-side/`](https://vercel-mcp-reference.vercel.app/client-side/) | The host/client perspective: consent UX, multi-server composition, sampling, elicitation, rendering untrusted tool output, credential brokering | Stable |
| [`testing/`](https://vercel-mcp-reference.vercel.app/testing/) | Unit, integration, and conformance testing for MCP servers: vitest, in-memory transports, MCP Inspector, and asserting the negatives | Stable |
| [`observability/`](https://vercel-mcp-reference.vercel.app/observability/) | Structured logging on Vercel, tracing, metrics for tool invocations, redaction | Stable |
| [`deployment/`](https://vercel-mcp-reference.vercel.app/deployment/) | Vercel deployment mechanics: `vercel.json` anatomy, environments, Deployment Protection, rollbacks, log drains, cost shape | Stable |
| [`examples/`](https://vercel-mcp-reference.vercel.app/examples/) | Narrative index of the runnable TypeScript examples under top-level `examples/` (`examples/minimal-server`, in the repository) and its siblings | Stable |
| [`glossary/`](https://vercel-mcp-reference.vercel.app/glossary/) | Plain-language definitions of MCP and Vercel terms, cross-linked from every page | Stable |

## Reading paths

| If you are a... | Suggested order |
|---|---|
| Engineer | [`getting-started/`](https://vercel-mcp-reference.vercel.app/getting-started/) → [`internals/`](https://vercel-mcp-reference.vercel.app/internals/) → [`patterns/`](https://vercel-mcp-reference.vercel.app/patterns/) → [`deployment/`](https://vercel-mcp-reference.vercel.app/deployment/) → the runnable examples |
| Architect | [`getting-started/`](https://vercel-mcp-reference.vercel.app/getting-started/) → [`internals/`](https://vercel-mcp-reference.vercel.app/internals/) (especially [serverless sessions](https://vercel-mcp-reference.vercel.app/internals/serverless-sessions/)) → [`patterns/`](https://vercel-mcp-reference.vercel.app/patterns/) (adapter, sidecar, facade, orchestrator) |
| Security / governance | [`security/`](https://vercel-mcp-reference.vercel.app/security/) → [`patterns/`](https://vercel-mcp-reference.vercel.app/patterns/) (least privilege, trust boundaries) → [`internals/`](https://vercel-mcp-reference.vercel.app/internals/) (statelessness, capability negotiation) → [`client-side/`](https://vercel-mcp-reference.vercel.app/client-side/) (consent) |
| Non-technical | [`getting-started/`](https://vercel-mcp-reference.vercel.app/getting-started/) → [`glossary/`](https://vercel-mcp-reference.vercel.app/glossary/) → the plain-language openings of [`internals/`](https://vercel-mcp-reference.vercel.app/internals/) pages |

The [getting-started page](https://vercel-mcp-reference.vercel.app/getting-started/) carries a more detailed version of these paths, with per-page ordering.

## Conventions

- **Frontmatter is mandatory** on every page: `title`, `audience` (a subset of engineer, architect, security, non-technical; order signals the primary audience), `spec_version`, `last_reviewed`, and `status` (`stable`, `draft`, or `needs-update`).
- **`spec_version` is per-page by design.** It names the MCP spec revision the page was verified against, currently `2026-07-28`. When a new revision lands, pages are individually reviewed and bumped; a stale version is a visible fact, not a hidden one. The runnable examples carry their own stack and wire-version note in the [examples index](https://vercel-mcp-reference.vercel.app/examples/), because SDK wire support can trail a published revision.
- **Citations live in a per-page `## Bibliography`** with fully resolved URLs. There is no global reference list, and no orphaned `[N]`-style markers.
- **Layered depth**: pages open in plain language, then go formal (protocol rules), then diagram, then details, then security, then a runnable example link, then the bibliography. Pages tagged `non-technical` always open with the plain-language layer.
- **Diagrams are Mermaid**, in the page source, and render on GitHub. A dedicated lint parses every diagram with the real mermaid parser, because the site build does not.
- **Prose stays implementation-agnostic** where it can; TypeScript- and Vercel-API-specific detail lives in the examples and is linked from the page.

See `CONTRIBUTING.md` (in the repository) for the page templates, the review process, and the standing spec-update workflow.

## Where to look now

- [Getting started](https://vercel-mcp-reference.vercel.app/getting-started/) - the first read for every audience, ending in a 10-minute deploy.
- [Serverless sessions](https://vercel-mcp-reference.vercel.app/internals/serverless-sessions/) - the flagship page on what changes when MCP runs on functions instead of daemons.
- [Security checklist](https://vercel-mcp-reference.vercel.app/security/checklist/) - the printable pre-deploy gate; every pattern page deep-links into it.

## About this project

`vercel-mcp-reference` is community-maintained by forward deployed engineers (FDE): practitioners who build and ship MCP servers on Vercel for customers and wrote down what they learned. It is an independent reference. Vercel and Anthropic are not involved in writing, reviewing, hosting, or publishing it; neither company is affiliated with it, endorses it, or has published it, and nothing here is official Vercel or Anthropic documentation. Where a claim matters, every page cites the MCP specification and `vercel.com/docs` directly, so you can verify it against the primary source.

**For AI agents.** The published site ships the reference in the [llms.txt](https://llmstxt.org/) format so a coding agent can consume it directly: <https://vercel-mcp-reference.vercel.app/llms.txt> is the index (one link and one-line description per page, grouped by section), <https://vercel-mcp-reference.vercel.app/llms-full.txt> is every page's markdown in reading order, and each page is also served as plain markdown at its own URL with `.md` in place of the trailing slash (for example <https://vercel-mcp-reference.vercel.app/patterns/adapter.md>). Point your agent at the index, or at the full file when it needs the whole reference in context.

"Vercel" and "Next.js" are trademarks of Vercel, Inc.; "Model Context Protocol" originates from Anthropic. These names are used only to describe compatibility and subject matter. The full trademark note (`README.md`, in the repository) sits in the repository README next to the licenses (code under Apache-2.0, documentation under CC-BY-4.0).

## Bibliography

- Model Context Protocol, official site - <https://modelcontextprotocol.io>
- Model Context Protocol Specification, *Architecture*, version 2026-07-28 - <https://modelcontextprotocol.io/specification/2026-07-28/architecture>
- Vercel Documentation, *Deploy MCP servers to Vercel* - <https://vercel.com/docs/mcp/deploy-mcp-servers-to-vercel>