vercel-connect

Vercel Connect Skill

Overview

Vercel Connect gives applications short-lived provider credentials without storing provider API keys or refresh tokens in project environment variables. A Vercel deployment authenticates with its project OIDC token. External CI or non-Vercel runtimes can pass a scoped Vercel access token through options.vercelToken.

Connectors are owned by a Vercel team. A consuming project and environment must be linked to the connector before it can request credentials. The connector UID, such as slack/acme-slack, is the stable identifier used by the SDK and CLI. Always use the UID or scl_... ID returned by create or list.

When to Use Vercel Connect

Use Vercel Connect when you need to:

• Send messages via Slack (as a bot or on behalf of a user)
• Access GitHub repositories or APIs
• Connect to any third-party system that requires OAuth tokens or API credentials
• Obtain scoped, short-lived provider credentials for authenticated API calls
• Forward provider events to applications through Vercel Connect triggers

Modes of tokens

The SDK supports four subject types. Pick based on what's acting:

• user: actions performed on behalf of a specific end user (e.g., post a Slack message as the user). Requires a user id and optional issuer.
• app: actions performed as the app itself (e.g., post as a Slack bot or use a GitHub installation). It skips per-user consent but may still require a provider installation or supported app grant.
• jwt-bearer: federated identity through the OAuth JWT-bearer grant. Pass sub (required), plus optional iss, aud, and additionalClaims.
• token: token exchange. Pass { token } with an existing subject token; the SDK infers type: "token" in @vercel/connect 2.4.0+.

For user subjects, derive subject.id from a stable identity in the authenticated server-side session. Never accept it from a request body or other client input. Keep getToken(), Connect auth providers, and MCP clients on the server.

CLI

The vercel connect CLI operates in the selected Vercel team and supports machine-readable output with --format=json or -F json.

Use the full lifecycle instead of assuming connector creation also authorizes a project:

# Inspect connectors linked to the current project, or all team connectors
vercel connect list
vercel connect list --all-projects

# Inspect supported setup options, then create a connector
vercel connect create <service> --help
vercel connect create <service>

# Link the connector to the current project and selected environments
vercel connect attach <connector>

# Request a scoped provider token
vercel connect token <connector> --subject app

The CLI also supports detach, update, remove, and open. Run vercel connect <command> --help before using optional installation, scope, trigger, branch, or custom-environment flags.

Use current-project behavior from a Vercel-linked project directory. Creating a connector and attaching it are distinct operations. Connector creation or token authorization may open a browser. Show the returned URL and wait for the person to finish the provider flow. --yes permits automatic browser opening; it does not force reauthorization.

vercel connect create <service> supports 100+ services (for example slack, github, microsoft, linear, snowflake, salesforce, notion, okta), plus any OAuth or MCP server URL. Run vercel connect create <service> --help to see that service's products, connection methods (oauth, api-key, mcp, custom-server, etc.), and required credentials before registering it.

For MCP servers there are two ways to register. For a known service, run vercel connect create <service> and pick the MCP connection method (e.g. vercel connect create linear --name my-agent gives the connector linear/my-agent). For any other OAuth-protected server, pass its URL (e.g. vercel connect create mcp.linear.app --name linear): Vercel discovers the OAuth endpoints from the URL and creates a custom OAuth connector (oauth/linear). Either way, attach it to the project with vercel connect attach <connector> before requesting tokens. The service name or URL you pass to create is not necessarily the MCP runtime URL; that goes in the connection's url.

JavaScript/TypeScript SDK (@vercel/connect)

For JavaScript/TypeScript code, use the @vercel/connect package directly:

import { getToken } from "@vercel/connect";

// Get a token for Slack bot
const token = await getToken("slack/acme-slack", {
  subject: { type: "app" }, // If sending as a bot, or else use "user"
});

// Use the token
const response = await fetch("https://slack.com/api/chat.postMessage", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel: "C1234567890",
    text: "Hello from Vercel Connect!",
  }),
});

On Vercel, the SDK reads VERCEL_OIDC_TOKEN automatically. For local development, run vercel link followed by vercel env pull. Development OIDC tokens expire, so pull again when authentication fails. For external CI or non-Vercel hosting, pass a scoped Vercel access token through the third options argument.

Use getToken() immediately before calling the provider and let the SDK cache identical requests. Scope each SDK request to what it needs with installationId, scopes, audience, resources, or authorizationDetails. The CLI supports subject, installation, and scopes, but not every SDK field. Do not invent CLI flags for SDK-only parameters.

Use these root APIs when needed:

• getTokenResponse() for token metadata such as expiry and connector details.
• getConnectorMetadata() to inspect connector metadata and provider-specific public configuration.
• startAuthorization() after UserAuthorizationRequiredError to begin user consent.
• revokeToken() and deleteTokenCacheEntry() for revocation and cache eviction.
• forceRefresh and validityBufferMs only when the default cache behavior does not fit the call.

Passport-authenticated users: @vercel/passport

If the application already authenticates users with Passport, pass the identity returned by requireIdentity() directly as the Connect subject. There is no need to manually construct a separate user subject:

import { getToken } from "@vercel/connect";
import { requireIdentity } from "@vercel/passport";

const identity = await requireIdentity();

const token = await getToken("slack/xaa-slack", {
  subject: identity,
  scopes: ["users:read"],
});

Keep both calls on the server. Replace slack/xaa-slack with your linked connector UID and request only the scopes needed by the operation; users:read is the scope used in this example. Passport supplies the authenticated user identity, while Connect supplies the provider API token. Connector attachment and provider authorization requirements still apply.

eve agents: @vercel/connect/eve

When the project is built on eve, prefer the connect helper over calling getToken directly inside connection definitions. It wires token requests and interactive authorization into eve's connection runtime:

// agent/connections/linear.ts
import { defineMcpClientConnection } from "eve/connections";
import { connect } from "@vercel/connect/eve";

export default defineMcpClientConnection({
  url: "https://mcp.linear.app/mcp",
  description: "Linear workspace: issues, projects, cycles, and comments.",
  auth: connect("linear/my-agent"),
});

Key points for the agent:

• Omit principalType for the default per-user OAuth flow, or set principalType: "app" for app-scoped tokens.
• Pass the connector UID directly with connect("linear/my-agent"), or use connect({ connector: "linear/my-agent" }) when you need options.
• For scopes, audiences, or authorizationDetails, pass them through tokenParams. For a custom challenge prompt, pass instructions. Both are optional.
• eve is an optional peer dependency, so the rest of @vercel/connect (CLI, getToken, etc.) is unaffected for non-eve consumers.

Slack channel: connectSlackCredentials

For eve Slack channels (agent/channels/slack.ts), use connectSlackCredentials(connector) from @vercel/connect/eve. It returns a complete SlackChannelCredentials object. Both the bot token and inbound webhook verification are handled by Vercel Connect, so you do not need SLACK_BOT_TOKEN or SLACK_SIGNING_SECRET env vars:

// agent/channels/slack.ts
import { slackChannel } from "eve/channels/slack";
import { connectSlackCredentials } from "@vercel/connect/eve";

export default slackChannel({
  credentials: connectSlackCredentials("slack/my-agent", {
    installationId: "inst_workspace_xyz",
  }),
});

What the helper wires up:

• botToken: a function that requests an app token when the channel needs it. Connect stores and refreshes installation credentials.
• webhookVerifier: a Vercel OIDC verifier (vercelOidc()). Vercel Connect forwards verified Slack webhooks to your app as signed Vercel OIDC requests; the helper verifies that signature instead of the raw Slack signing secret.

Without an explicit installationId, a channel helper uses the connector's default installation. It does not infer the correct installation from an inbound workspace or organization. Multi-tenant applications must resolve a trusted installation mapping and pass the resulting ID as the helper's second argument.

Use this whenever the project is on eve + Vercel Connect. It is the one-liner for both outbound posts and inbound webhook auth.

GitHub channel: connectGitHubCredentials

For eve GitHub channels (agent/channels/github.ts), use connectGitHubCredentials(connector) from @vercel/connect/eve. It returns a complete GitHubChannelCredentials object. eve uses th

---

Content truncated.