# vercel-deployment-mcp

[![CI](https://github.com/addiplus/vercel-deployment-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/addiplus/vercel-deployment-mcp/actions/workflows/ci.yml)

A reference [Model Context Protocol](https://modelcontextprotocol.io) 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

| Tool | Description |
| --- | --- |
| `list_projects` | List projects visible to the configured account/team (search, limit) |
| `get_project` | Fetch one project by ID or name |
| `list_deployments` | List recent deployments (filter by project, state, limit) |
| `get_deployment` | Fetch one deployment by ID or URL, including current state |

`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:

```bash
npm install @addiplus/vercel-deployment-mcp
```

Or run it directly without installing:

```bash
npx @addiplus/vercel-deployment-mcp
```

From source:

```bash
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

| Variable | Required | Purpose |
| --- | --- | --- |
| `VERCEL_TOKEN` | yes | Vercel access token (create in account settings) |
| `VERCEL_TEAM_ID` | no | Scope requests to a team |
| `VERCEL_MCP_MIN_INTERVAL_MS` | no | Minimum milliseconds between the start of one Vercel API request and the next (default `250`) |
| `VERCEL_MCP_MAX_CONCURRENT` | no | Maximum number of Vercel API requests in flight at once (default `4`) |

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

| Limit | Value |
| --- | --- |
| Longest `search` value | 4096 characters |
| Longest `projectId`, `state`, `idOrName`, `idOrUrl` value | 512 characters |
| Largest accepted protocol frame | 10485760 bytes |
| Highest accepted `VERCEL_MCP_MIN_INTERVAL_MS` | 60000 |

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):

```json
{
  "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