vercel-deployment-mcp

A reference Model Context Protocol server for observing Vercel projects and deployments over stdio.

This is a community reference implementation focused on deployment-workflow patterns. It is not a replacement for Vercel's own MCP offering. Its purpose is to demonstrate, in a small and readable codebase, how a deployment-focused MCP server can handle configuration cleanly and behave predictably on short-lived infrastructure.

Tools

list_projects and list_deployments each return a single page of up to limit results (default 20, max 100). There is no cursor pagination; narrow the request with search, projectId, or state to see more specific results.

Install

From npm:

npm install @addiplus/vercel-deployment-mcp

Or run it directly without installing:

npx @addiplus/vercel-deployment-mcp

From source:

git clone https://github.com/addiplus/vercel-deployment-mcp.git
cd vercel-deployment-mcp
npm install
npm run build
npm test

Running the test suite needs a newer Node than the server does. vitest 4.1.10 declares engines.node of ^20.0.0 || ^22.0.0 || >=24.0.0, and the vite 8.1.3 this lockfile pins narrows that to ^20.19.0 || >=22.12.0. The suite runs on the intersection of the two, ^20.19.0 || ^22.12.0 || >=24.0.0: the 20 line from 20.19.0, the 22 line from 22.12.0, and 24 and above. The 23 line is outside it, because vitest does not cover 23. CI runs 22 and 24. The published package itself still runs on Node >=18 per engines.

Configuration

On an HTTP 429 with a numeric Retry-After header of 10 seconds or less, the server waits that long and retries the request once; any other 429 is surfaced as an error on the first attempt.

Limits

The frame limit counts the message and not the newline that delimits it, so a message of exactly 10485760 bytes is accepted. Everything before that newline is the message, a carriage return sitting just in front of it included.

Each of these limits has its own behaviour above the value in the table. An over-long argument fails input validation: the call comes back as a JSON-RPC -32602 invalid-params result, no Vercel API request is made, and nothing is written to stderr for it. A frame above the frame limit is dropped, one line on stderr says so, and the connection keeps serving. An interval above the ceiling is not refused, it is reduced to the ceiling: the server runs with the reduced value, and one line on stderr says so the first time it makes a Vercel API request. The same stderr report repeated back to back is written twice at most, the second time to say that further identical reports are suppressed.

initialize and ping are answered at any time. tools/list and tools/call are answered only once the client has completed the initialization handshake: an initialize request the server can answer, followed by notifications/initialized. Both halves are required, so the notification on its own completes nothing, and neither does an initialize the server rejects. A client that writes both halves and its first call in a single write is served, rather than being refused for not waiting for the initialize response. Before the handshake, those two methods are refused with JSON-RPC error -32600 and no Vercel API request is made.

Example client configuration (Claude Desktop / Claude Code):

{
  "mcpServers": {
    "vercel-deployment": {
      "command": "npx",
      "args": ["-y", "@addiplus/vercel-deployment-mcp"],
      "env": { "VERCEL_TOKEN": "…" }
    }
  }
}

When running from a source checkout, use "command": "node" with "args": ["/path/to/vercel-deployment-mcp/dist/index.js"] instead.

Design principles

First written 2026-07-10 and kept current with the code since; claim 1 was restated when error text began being redacted once, where it becomes client-visible. Each claim below is implemented in code and verified by the test suite where testable (test/); design properties cite the implementing code.

1. Configured values never appear in an error. The access token is read only from the environment. Error text is shaped, size-bounded, and passed through a redaction guard once, where it becomes client-visible text, so an upstream API message cannot echo the token or the team id back (src/vercel.ts); the fixed hint appended after that bound is text this server writes and carries nothing to replace. A successful result is a fixed projection of the upstream body and is not redacted, so a team identifier that the Vercel API itself returns inside a deployment URL still appears there.
2. stdout belongs to the protocol. All diagnostics go to stderr (src/index.ts), so no log line can leak into a tool response.
3. Minimal footprint. The tools are read-only observations of projects and deployments; the server requests nothing beyond what those reads need.
4. Stateless by design. Configuration is re-read from the environment on every tool call (verified in test/tools.test.ts), so behavior is identical on long-lived hosts and short-lived workers. The one piece of module-level state is a request throttle (src/vercel.ts) that spaces out and caps concurrent Vercel API calls; its interval and concurrency settings are read once at first use, and it holds no credentials or response data.

Roadmap

• Deployment actions with an explicit out-of-band approval step (exploring the patterns discussed in MCP spec issues #2919/#2920 around multi-round tool results on stateless transports).
• Standardizing how server.json describes stdio package install manifests and how clients convert them into local configuration files (spec issue #2963, registry issue #749).

License

MIT