vercel-connect

Rather than keeping a password for Slack, GitHub or Linear, an app asks Vercel for a short-lived pass each time it needs one, either as itself or on behalf of the person using it.

WHEN TO USE

SCOPE

USE FOR

Post a Slack message as your app's bot without hardcoding a bot token.
Let an agent call a third-party MCP server such as Linear on a user's behalf.
Wire GitHub or Slack webhook auth into an eve agent without managing secrets by hand.
Plug a third-party login into Better Auth or Auth.js as an OAuth provider.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (12)

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 three 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.

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.

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 the installation token directly, while Vercel Connect stores and refreshes provider credentials. Pass an explicit trusted installationId for multi-tenant routing. You do not need GITHUB_APP_PRIVATE_KEY, GITHUB_APP_ID, GITHUB_INSTALLATION_ID, or GITHUB_WEBHOOK_SECRET env vars:

// agent/channels/github.ts
import { githubChannel } from "eve/channels/github";
import { connectGitHubCredentials } from "@vercel/connect/eve";

export default githubChannel({
  botName: "my-agent",
  credentials: connectGitHubCredentials("github/myagent"),
});

What the helper wires up:

installationToken: a function that calls getToken(connector, { subject: { type: "app" } }). The helper pins subject to "app" because GitHub installation tokens are app-scoped.
webhookVerifier: a Vercel OIDC verifier (vercelOidc()). Vercel Connect forwards verified GitHub webhooks to your app as signed Vercel OIDC requests; the helper verifies that signature instead of the raw GitHub webhook secret.

Linear channel: `connectLinearCredentials`

For eve Linear channels (agent/channels/linear.ts), use connectLinearCredentials(connector) from @vercel/connect/eve. It returns a complete LinearChannelCredentials object. Vercel Connect manages the Linear app access token and webhook auth, so you do not need LINEAR_ACCESS_TOKEN or LINEAR_WEBHOOK_SECRET env vars:

// agent/channels/linear.ts
import { linearChannel } from "eve/channels/linear";
import { connectLinearCredentials } from "@vercel/connect/eve";

export default linearChannel({
  credentials: connectLinearCredentials("linear/myagent"),
});

What the helper wires up:

accessToken: a function that calls getToken(connector, { subject: { type: "app" } }). The helper pins subject to "app" because Linear Agent tokens are app-scoped.
webhookVerifier: a Vercel OIDC verifier (vercelOidc()). Vercel Connect forwards verified Linear webhooks to your app as signed Vercel OIDC requests; the helper verifies that signature instead of the raw Linear webhook secret.

The eve entrypoint also provides Connect credential helpers for Discord, Microsoft Teams, Linq, and Photon channels. connectOAuth() verifies Connect OAuth-gateway bearer tokens for inbound routes; use connect() for MCP client connection authorization. Check the current eve integration docs for subject creation, automatic provisioning, validation, eviction, and revocation options instead of copying configuration between connector types.

HTTP API

For other languages, request a token directly from the Vercel API. Authenticate with the project's Vercel OIDC token or a scoped Vercel access token. A connector UID containing / must be URL-encoded as one path segment:

With a Vercel access token, request only an app subject or the access-token owner's own user subject. Use a project OIDC token to request a provider credential for a different user subject.

# Get a token via HTTP
POST https://api.vercel.com/v1/connect/token/slack%2Facme-slack
Authorization: Bearer <VERCEL_OIDC_TOKEN | Vercel access token>
Content-Type: application/json

{ "subject": { "type": "user", "id": "user_123" } }

The response is JSON with a token field (plus expiresAt, connector, and other metadata).

Python Example

import os
import requests

# Get token from Vercel Connect
connect_response = requests.post(
    "https://api.vercel.com/v1/connect/token/slack%2Facme-slack",
    headers={"Authorization": f"Bearer {os.environ['VERCEL_OIDC_TOKEN']}"},
    json={
        "subject": {"type": "app"},
    },
)
token = connect_response.json()["token"]

# Use the token
slack_response = requests.post(
    "https://slack.com/api/chat.postMessage",
    headers={"Authorization": f"Bearer {token}"},
    json={"channel": "C1234567890", "text": "Hello from Vercel Connect!"}
)

Framework adapters

Choose the adapter by job:

@vercel/connect/ai-sdk and @vercel/connect/mcp: use connectAuthProvider() to authenticate MCP clients and coordinate consent. Provider consent and AI SDK tool approval are separate decisions.
@vercel/connect/tanstack-ai: use its Connect transport and consent helpers with TanStack AI.
@vercel/connect/chat: supply credentials for supported Chat SDK adapters. Connect-trigger OIDC verification applies to Slack, Discord, Microsoft Teams, GitHub, and Linear. Notion and Telegram use their native inbound mechanisms.
@vercel/connect/eve: authorize eve connections, supply channel credentials, and authenticate inbound OAuth routes.
@vercel/connect/betterauth and @vercel/connect/authjs: sign users into your application through a Connect OAuth provider.

Better Auth and Auth.js

These adapters sign users into the application. They do not return a provider API token. If the app also needs to call the provider API, use the root SDK's getToken() with the appropriate subject and scopes.

Better Auth: `@vercel/connect/betterauth`

Optional peer dependency: better-auth. Pass the connector through Better Auth's genericOAuth plugin. Connector UIDs can contain a / (e.g. linear/myagent), and Better Auth additionally requires a providerId:

import { genericOAuth } from "better-auth/plugins/generic-oauth";
import { connect } from "@vercel/connect/betterauth";

genericOAuth({
  config: [connect({ providerId: "linear", connector: "linear/myagent" })],
});

Auth.js: `@vercel/connect/authjs`

Optional peer dependency: @auth/core. Use the connector as an OAuth2Config provider. Connector UIDs can contain a / (e.g. linear/myagent), and Auth.js additionally requires an id:

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

const providers = [connect({ id: "linear", connector: "linear/myagent" })];

Project links, installations, and environments

vercel connect attach <connector> grants the linked project access in selected environments. Use detach to remove that link.
Project links authorize token requests. They do not isolate a connector's provider installations. Use separate connectors when production and non-production must be isolated at the provider level.
Installation-backed connectors may require installationId. Never guess one when multiple installations are available.
Custom Environments and branch targeting are configured through project-link and trigger options. Inspect current CLI help before changing them.

Triggers and observability

Triggers are opt-in destinations that forward supported provider events to an application. Connect signs forwarded requests, retries documented 5xx failures, and limits the number of destinations per connector. Configure trigger paths and environment or branch targeting explicitly rather than assuming connector creation adds them.

Use connector event history, correlation IDs, and configured drains when diagnosing token, installation, authorization, or trigger failures. Do not log raw provider tokens.

Recommended workflow

Link the local directory with vercel link, then pull a development OIDC token with vercel env pull.
Run vercel connect list and, when needed, vercel connect list --all-projects.
If no suitable connector exists, inspect vercel connect create <service> --help, create it, and capture the returned UID or ID.
Attach the connector to the consuming project and required environments.
For CLI token requests, choose the narrowest practical subject, installation, and scopes. In SDK code, also use audience, resources, or authorizationDetails when the provider requires them.
If user consent or provider installation is required, surface the authorization URL or typed error and wait for completion.
Call the provider with the short-lived credential. In SDK code, request it at use time and let the cache refresh it.
Configure triggers separately when inbound events are required, then verify delivery with event history and correlation IDs.

Sources of truth

Vercel Connect changes quickly. Before generating commands or framework code, consult:

MCP connection required

1 FOR YOU · 1 FOR THE AGENT

All items below are required.

01
Create a Connect connector and attach it to the project
From the Vercel-linked project or agent folder, run vercel connect create <service> (for example slack, github, linear, or an OAuth-protected server's address such as mcp.linear.app) and complete any browser consent it opens, then run vercel connect attach <connector> to link it to the project; creating a connector does not authorize the project on its own.
02
Fetch a token for that connector before calling the API
Run vercel connect token <connector> --subject user|app (or call getToken() from @vercel/connect) to obtain a short-lived token, then use it as a Bearer token against the third-party API.

This skill ships inside the Vercel Plugin. Listed package contents include 4 slash commands, 3 agents, hooks and an MCP server. Installed components and skill versions may vary by AI tool.

Install just this skill

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add vercel/vercel-plugin --skill "vercel-connect" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

Install the whole plugin

This route installs the Vercel Plugin package selected for your AI tool.

Run this command in a terminal

npx plugins add vercel/vercel-plugin

Plugins CLI 1.3.4 sends an install report by default, including the source exactly as entered, plugin names, target tools and scope; it does not check whether repositories are public or private. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable this report. For data sent by an installed plugin, check that plugin's documentation.

Open plugin page ↗

What's inside

Files included with this skill.

View on GitHub

Vercel Connect Skill

Overview

When to Use Vercel Connect

Modes of tokens

CLI

JavaScript/TypeScript SDK (@vercel/connect)

eve agents: @vercel/connect/eve

Slack channel: connectSlackCredentials

GitHub channel: connectGitHubCredentials

Linear channel: connectLinearCredentials

HTTP API

Python Example

Framework adapters

Better Auth and Auth.js

Better Auth: @vercel/connect/betterauth

Auth.js: @vercel/connect/authjs

Project links, installations, and environments

Triggers and observability

Recommended workflow

Sources of truth

MCP connection required

Install just this skill

Install the whole plugin

Run this command in a terminal

What's inside

More skills

MCP keyword matches

JavaScript/TypeScript SDK (`@vercel/connect`)

eve agents: `@vercel/connect/eve`

Slack channel: `connectSlackCredentials`

GitHub channel: `connectGitHubCredentials`

Linear channel: `connectLinearCredentials`

Better Auth: `@vercel/connect/betterauth`

Auth.js: `@vercel/connect/authjs`