Docs for Engineers

Building and integrating MCP servers and clients. 49 pages tagged engineer. See all audiences.

Overview 1

• Overview 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 1

• Getting started with MCP on Vercel 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 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.

Testing 1

• Testing patterns 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 1

• Observability patterns Structured logging, tracing, and metrics for MCP tool invocations on Vercel, with correlation ids, redaction rules, and log drains.

Deployment 1

• Deploying MCP servers on Vercel Vercel deployment mechanics for MCP servers: vercel.json anatomy, environments, Deployment Protection, rollbacks, log drains, and cost shape.

Examples 15

• 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.
• Build-it-yourself prompts Copy-paste prompts that rebuild each runnable example with an AI coding agent: same stack, same behaviors, same tests.
• Prompt: 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: resources-server Generation prompt for resources-server: a resources-only MCP server with static resources and resource templates, no tools.
• Prompt: 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.
• Prompt: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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.

Glossary 1

• Glossary Plain-language definitions of the MCP and Vercel terms used across the reference, alphabetized and cross-linked from every page.