Your agent needs to deploy, inspect, and debug Vercel projects. Vercel ships a hosted MCP server at mcp.vercel.com and a REST API at api.vercel.com, and both are official. They are not two views of the same surface: different capability coverage, different auth models, and one constraint on the MCP side that disqualifies most production agents before capability even matters. Here is how to pick.
Two objects, two audiences. One is aimed at the developer sitting in front of an AI assistant, the other at software you deploy.
Vercel MCP is Vercel's official remote MCP server, hosted at https://mcp.vercel.com, implementing the MCP Authorization and Streamable HTTP specifications. Auth is browser-based OAuth. It is available in Beta on all plans.
The documented client list is a list of assistants: Claude Code, Claude, ChatGPT, Codex CLI, Cursor, VS Code with Copilot, Devin, Raycast, Goose, Windsurf, and the Gemini tools. Official docs: Use Vercel's MCP server and the tools reference.
The REST API lives under https://api.vercel.com and is authenticated with Authorization: Bearer <TOKEN>. Team-owned resources are reached by appending teamId as a query parameter. Rate limit state comes back in X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset, with a 429 when you exceed it.
The current reference index lists more than 300 endpoints across 36 resource groups, including deployments, projects, environment, dns, drains, webhooks, security, rolling-release, sandboxes, and web-analytics. Official docs: Vercel REST API Reference.
The capability gap is real, and it is not evenly distributed. MCP covers the read-and-debug loop well. Everything that configures the platform is REST-only.
The MCP server is built for a human debugging a project through an assistant. It reads deployments, reads logs, searches docs, and resolves toolbar comments. Two areas are genuinely ahead of the documented REST surface: Agent Runs traces and Vercel Toolbar threads.
Everything that changes platform configuration is absent. No environment variables, no DNS, no drains, no webhooks, no firewall rules, no rollbacks. A release-management agent or an incident-response agent hits that wall on its second real task.
Vercel MCP is Beta and the tool list moves. Vercel's MCP overview page advertises Web Analytics querying, which the tools reference does not currently enumerate. There is no version header to pin, so a schema change arrives whenever Vercel ships one.
This is where the decision actually gets made for production agents, and it is not the usual OAuth-versus-API-key argument.
Vercel maintains an allowlist of approved MCP clients and requires an explicit consent screen on every client connection, which is how it defends against the confused deputy problem. Vercel is clear about the intent: only clients that meet its standards for authorization, data handling, and protocol adherence are approved.
For an IDE assistant, this is a security feature. For your product, it is a gate. Teams building third-party agent platforms have reported that dynamic client registration against mcp.vercel.com is rejected with invalid_redirect_uri until their redirect URI is approved, and they have had to request allowlisting through Vercel's community forum.
Your agent is not Cursor. If you are building a deployment copilot inside your own SaaS product, the direct path to mcp.vercel.com is not open to you by default, and the fix is a human approval process at Vercel rather than a configuration change on your side.
That is an architectural constraint, not a scope you forgot to request. Plan around it or take the API path.
The REST API gives you three credential models with different lifecycle properties. The first one you own outright.
Account or team access tokens are created in account settings, scoped to the account or to specific teams at creation time, with a selectable expiration. The value is shown once. They are right for internal tooling and single-tenant automation, and wrong for multi-tenant products, because the credential is yours rather than the end user's.
The other two models are delegated, and they differ sharply in lifetime.
Vercel integration scopes are not a one-time decision. Additions and upgrades require review and confirmation, and every affected user and team owner is emailed to complete it. Removals and downgrades apply immediately without confirmation.
Translate that into agent terms. Ship a new tool that needs project-env-vars and you have not shipped a feature; you have started a re-consent campaign across every tenant. Provision the scope set your roadmap needs before you have users, not after. This is one of the more subtle tool calling auth production problems teams run into.
Nearly every authenticated Vercel MCP tool requires teamId, and list_projects requires it too. An agent with no cached team context spends its first tool call on list_teams before it can do anything useful.
On the REST side, teamId is a query parameter you set once from your own tenant record. Small difference per call, real difference across thousands of runs.
Both paths hand you an operational surface. They are not the same surface, and neither one includes credential lifecycle.
Vercel owns hosting, transport, and tool schemas. You own the OAuth consent flow per user, the token that flow produces, refresh behavior, revocation handling, and adapting when the Beta tool list changes underneath you.
You also own the failure mode where a user revokes access in Vercel and your agent finds out through a 401 mid-run.
You own more, and you get determinism in exchange. Endpoint selection, per-endpoint versioning (/v13/deployments and /v10/projects are versioned independently), pagination, retry logic against X-RateLimit-Reset, and the full token lifecycle.
One specific failure to instrument: when an integration configuration is disabled, API requests fail with 403 and a code of integration_configuration_disabled, and drains stop receiving logs. That is a silent data gap unless you are watching for it.
MCP tool schemas change when Vercel updates the hosted server, with no version contract available to you. REST endpoints are versioned per endpoint and deprecations go through the changelog.
For a scheduled pipeline where an unexpected schema change is an incident, the versioned surface is the more predictable dependency. This tradeoff is a core theme when comparing MCP against lower-level interfaces.
Both are correct answers for different agents. The split is cleaner here than for most tools in this series.
Pick either path and you still end up holding one Vercel credential per user. The token type differs; the infrastructure does not.
Forty engineers across eight customer teams means forty OAuth grants to store encrypted and isolated per tenant. Sign in with Vercel access tokens expire hourly, and their refresh tokens are single use, so a lost rotation is a broken connection rather than a retryable error.
Users can also revoke at any time from Vercel, and revoking an access token revokes its refresh token with it. Your agent has no way to know that happened until a call fails. This is the core challenge covered in depth in our guide on how to handle token refresh for AI agents.
Scalekit's Vercel connectors handle the OAuth flow, encrypted token storage, proactive refresh, and per-user scoping for both paths, so the MCP versus API decision does not change your auth infrastructure. Credentials never touch the agent runtime or the model context.
Scalekit ships both objects as separate connectors so you can use either surface, or both, behind one credential layer.
The Vercel connector wraps the REST API and exposes 56 tools spanning aliases, checks, deployments, DNS, domains, Edge Config, environment variables, projects, teams, and webhooks. The Vercel MCP connector wraps Vercel MCP and exposes 19 tools including vercelmcp_getruntimelogs, vercelmcp_getdeploymentbuildlogs, and vercelmcp_searchverceldocumentation.
Both are configured with an OAuth integration you create in the Vercel Integrations Console, so you supply your own client ID and secret rather than relying on dynamic client registration.
The scope string you enter in Scalekit must match exactly what you enabled on the Permissions tab of your Vercel integration, or authorization fails with invalid_scope. Scalekit's walkthrough shows the identity scopes (openid, profile, email, offline_access); the resource scopes your REST tools actually call include deployment, project, project-env-vars, team, user, domain, edge-config, and log-drain.
The connection_name in your code must also match the connection name configured in the Scalekit dashboard. This is the single most common integration error.
Install the SDK and create a connected account for the user. Scalekit returns an authorization link when the account is not yet active.
Before the agent sees a single tool, decide what it is allowed to see. list_scoped_tools does not return a connector catalog; it returns the tools the current user's connected account is authorized to call, which is the distinction between a per-user agent and a shared-credential agent.
The Vercel connector exposes 56 tools. At roughly 200 tokens each, handing the model the full catalog burns about 11,000 tokens before the agent does any work, and it gives a deployment-diagnosis agent the ability to call vercel_project_delete.
Scoping to the five or six tools the task needs cuts that overhead and shrinks the decision space the model chooses from. Surface reduction is the lever. Model upgrades help. They are not the lever. This pattern is central to how tool calling auth changes when you move from single-tenant to multi-tenant.
actions.langchain.get_tools() returns native StructuredTool objects, so the agent code carries no Scalekit-specific logic past initialization.
If you want the MCP-side capabilities, the code shape does not change. Configure the vercelmcp connection, then call execute_tool with the MCP tool name.
A standard MCP server exposes everything it has. A Virtual MCP server declares exactly which tools an agent can see and whose credentials it acts with, across multiple connections, behind one static endpoint.
Create the server once per agent role, not once per user.
The endpoint is static; the identity is not. Check that every connection is still active for this user, then mint a short-lived token bound to that user.
Note the negative space. The agent above cannot call vercel_project_delete, cannot mint an Edge Config read token, and cannot invite a team member, because those tools were never mapped onto its server. The agent sees only what you explicitly allow, not everything the connector exposes.
That is least privilege enforced at the tool level, and it is the difference between a demo and something you let run unattended against production deployments. This approach to credential ownership across agent tool-calling patterns determines your actual security posture in production.
Connect an assistant directly to mcp.vercel.com and the audit story ends at Vercel's own account activity. You cannot answer which of your users triggered which downstream call, under which grant, at which time.
Scalekit's auth logs record the authorization and token lifecycle behind every connected account, so a tool call against Vercel traces back to the user who authorized it and the grant it ran under. Logs can be exported to your SIEM or warehouse for alerting and compliance workflows. This kind of traceability is covered in detail in our post on audit trails for agent auth in B2B SaaS.
If your agent lives inside an approved AI client and its job is reading deployments, pulling logs, and searching docs with a developer present, use Vercel MCP. The setup cost is one command and Vercel maintains the server.
If your agent is your product, runs headless, or touches platform configuration, build against the Vercel REST API. The client allowlist is not a workaround problem, and the configuration surface simply is not on the MCP server.
Most production teams end up running both: MCP for the interactive developer experience, REST for the background pipeline. The credential layer underneath is identical either way, and that is the part that needs production-grade infrastructure.
Building deployment agents, incident-response agents, or release-notes agents on Vercel? Join the Scalekit Slack community and compare notes with other teams shipping the same thing.
Need help now: talk to an engineer.
Browse the connectors: Vercel connector docs and Vercel MCP connector docs.
Vercel MCP is a hosted remote MCP server at mcp.vercel.com that exposes roughly two dozen tools for reading deployments, logs, and docs via browser-based OAuth. The Vercel REST API is a versioned HTTP API with over 300 endpoints covering every platform capability. MCP is designed for developer assistants; the REST API is designed for software.
Not by default. Vercel maintains an allowlist of approved MCP clients. If your product is not on that list, dynamic client registration against mcp.vercel.com will be rejected. You must request allowlisting through Vercel, which is a human approval process rather than a configuration fix.
Environment variables, DNS records, webhooks, log drains, firewall and WAF configuration, rolling releases, edge cache invalidation, team member management, canceling or deleting deployments, and web analytics queries are all REST-only as of the current tool reference.
Three types: account or team access tokens (static, created in settings), integration OAuth tokens (long-lived, exchanged from a 30-minute authorization code), and Sign in with Vercel tokens (OIDC-based, one-hour access tokens with 30-day rotating refresh tokens).
Vercel requires every affected user and team owner to confirm scope additions and upgrades by email. One new scope for a new tool means every existing tenant must re-authorize before the feature works for them. You should provision your full intended scope set before acquiring users.
Scalekit provides two Vercel connectors — one for the REST API (56 tools) and one for Vercel MCP (19 tools) — both backed by the same OAuth credential layer. It handles token storage, proactive refresh, per-user scoping, and auth logs so credentials never reach the agent runtime or model context.
When you need MCP-exclusive capabilities (Agent Runs traces, Toolbar threads) for interactive developer workflows alongside REST-only operations (env vars, DNS, firewall rules) for background pipelines. Scalekit's Virtual MCP server lets you combine both behind one endpoint with per-agent tool mapping.
Revoking a Vercel access token also revokes its associated refresh token. Your agent has no advance warning and will receive a 401 on the next API call. Without proactive token monitoring and graceful reconnection flows, this causes silent failures in production.
