---
name: vercel-get-started
area: Getting Started
supported_surfaces: [cli, plugin, skills, mcp]
description: |-
  Hand your coding agent this playbook to set up Vercel: install the
  CLI, add Vercel platform guidance, and connect the official Vercel MCP server
  once for use across projects.
title: 'Onboard your agent to Vercel'
url: https://vercel.com/get-started.md
runtimes:
  [Claude Code, Cursor, Codex CLI, VS Code with Copilot, Windsurf, Gemini CLI]
---

# Set up Vercel for your AI coding agent

Use this playbook to prepare the current agent for Vercel. Install the CLI, guidance, and MCP connection once; link individual projects only when project operations require it.

## How to run

Run section 1 once per machine. Run sections 2 and 3 once per coding agent. In section 2, install either the Vercel Plugin or standalone skills based on what the current agent supports.

For Section 3, add the Vercel MCP, identify the current runtime and follow only its matching MCP route.

Perform actions yourself when terminal or file access is available. Global or user-scoped installation is the default. Pause only for user authentication, approval, or UI actions you cannot perform. Do not merely return commands for the user to copy.

## 1. Install the Vercel CLI

Check for an existing installation:

```sh
vercel --version
```

If the CLI is missing, install the latest version:

```sh
npm install --global vercel@latest
vercel --version
```

If the installed CLI reports that an update is available, run the same global install command. Use bare `vercel` commands for all subsequent operations.

If `whoami` reports that no user is authenticated, you can use `vercel signup` to create an account on the behalf of the user, or `vercel login` if they already have one.

Pause while the user completes sign-up or sign-in, then verify using:

```sh
vercel whoami
```

Do not create or link a Vercel project during global setup. Link a project later when a deployment or project-specific operation requires it.

## 2. Add Vercel guidance

Install either the Vercel plugin or standalone skills—not both.

### Preferred: Vercel plugin

Use the plugin when the current agent is listed as supported and Node.js 18+ and Bun are available:

```sh
node --version
bun --version
npx plugins add vercel/vercel-plugin
```

Install the plugin once for the current agent. Confirm it is enabled across projects and that a command such as `/vercel-plugin:status` is discoverable.

Reload only if the newly installed commands are missing.

### Fallback: standalone skills

Use this when the current agent cannot run the plugin:

```sh
npx skills list
npx skills add vercel-labs/agent-skills --global
npx skills list
```

Choose the current agent if prompted and confirm the installation path. The standalone pack is smaller than the plugin and does not include its complete command, agent, and automation system.

## 3. Connect Vercel MCP

Connect the shared Vercel MCP endpoint once to access Vercel projects, deployments, logs, and analytics across projects.

First confirm that the current client is supported:

https://vercel.com/docs/agent-resources/vercel-mcp

Before changing a MCP configuration file, inspect it and merge the `vercel` entry without replacing unrelated settings.

For clients supported by the Vercel CLI, configure the shared endpoint:

```sh
vercel mcp --clients "<client>"
```

Use the exact `<client>` value for the current runtime:

- Claude Code: `Claude Code`
- Cursor: `Cursor`
- VS Code with GitHub Copilot: `VS Code with Copilot`

This is the default. Use `--project` only when the user explicitly requests a project-scoped MCP connection.

### Claude Code

Manual user-scoped fallback:

```bash
claude mcp add --transport http vercel --scope user https://mcp.vercel.com
```

Inspect existing MCP entries before adding. To authenticate, open `/mcp`, select `vercel`, and choose the authentication action.

### Codex CLI

First inspect:

```bash
codex mcp list
```

Codex is not a supported `vercel mcp --clients` target. Its documented add command uses Codex's user-wide configuration:

```bash
codex mcp add vercel --url https://mcp.vercel.com
```

Codex should open a browser during setup. If the server exists but is not authenticated, run:

```bash
codex mcp login vercel
```

### Cursor

Manual fallback: merge this into `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "vercel": {
      "url": "https://mcp.vercel.com"
    }
  }
}
```

Cursor displays `Needs login` when authorization is required. Ask the user to click it.

### VS Code with GitHub Copilot

Run **MCP: Add Server**, choose **HTTP**, enter `https://mcp.vercel.com`, name it `Vercel`, and select **Global**. Then run **MCP: List Servers**, start Vercel, and allow authentication. If VS Code offers its alternate URL-handler authentication path, use that prompt.

### Windsurf

Merge this into `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "vercel": {
      "serverUrl": "https://mcp.vercel.com"
    }
  }
}
```

Refresh the MCP configuration in Windsurf after saving.

### Gemini CLI

Merge this into `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "vercel": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.vercel.com"]
    }
  }
}
```

Run Gemini CLI and use `/mcp list` to load the server.

### Common authorization and verification

Before authorizing, verify the endpoint is exactly:

```text
https://mcp.vercel.com
```

When a browser or consent screen opens, pause for the user to complete OAuth.

After authorization:

1. Call `search_vercel_documentation`.
2. Call the authenticated, read-only `list_teams` tool.
3. Refresh the client's MCP tools or server list if either is unavailable.
4. Start or resume a session, or reload or restart the client, only if refreshing does not load the server.

Keep human confirmation enabled for every MCP mutation. Connecting MCP gives the agent the access of the authorizing Vercel user.

## Completion

Report only verified state:

```text
▲ Vercel agent setup is ready
CLI: <version>, authenticated as <username>
Guidance: <plugin|skills|skipped>, global or user scope
MCP: <connected|skipped>, global shared endpoint, https://mcp.vercel.com
MCP config: <path|managed by Vercel CLI>
Authenticated MCP check: <list_teams succeeded|not requested>
Reload: <not needed|completed>
```

Sources:

- https://vercel.com/docs/cli
- https://vercel.com/docs/agent-resources/vercel-plugin
- https://vercel.com/docs/agent-resources/skills
- https://vercel.com/docs/agent-resources/vercel-mcp
- https://vercel.com/docs/cli/mcp