vercel-connect

Vercel Connect Skill

Overview

Vercel Connect enables to securely obtain scoped tokens for accessing third-party services on behalf of apps or users. It uses Vercel OIDC tokens to authenticate and exchange for Vercel Connect tokens via the Vercel API.

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 tokens for authenticated API calls

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, app-level GitHub access). No consent flow — fails terminally if the connector is not installed.
• jwt-bearer — RFC 7523 JWT-bearer exchange for connectors that accept a caller-minted assertion. Pass sub (required), plus optional iss, aud, and additionalClaims. Use when the third-party expects you to vouch for the subject via a signed JWT rather than an interactive OAuth grant.

Available Tools

All tools have --format=json option for machine-readable output.

1. Vercel Connect CLI (for Bash/Shell)

Use the vercel connect CLI for command-line operations. Use vercel connect --help to get available commands. The user needs to be authenticated to the Vercel CLI and the commands work within the scope of the user's currently selected Vercel team. For eg it will create & list Connect connectors created within the currently selected Vercel team.

Important! Always run vercel connect commands from the project or agent folder that will consume the connection (the directory containing package.json / vercel.json). Vercel Connect reads the local project context to auto-configure the connection — for example, picking a sensible connector name and uid, setting up project access to the connection, configuring webhooks and triggers. Running from the repo root or an unrelated directory skips this auto-configuration and you'll have to wire things up by hand. If the user invokes a vc connect command from elsewhere, cd into the closest matching project/agent folder first (or pass --cwd <DIR>).

Example commands:

# Create new Connect connector
vercel connect create <service>

# List existing Connect connectors
vercel connect list

# Get token
vercel connect token <connector> --subject user|app

Important! The vercel connect create and vercel connect token commands may open the browser for the user if there's a manual registration required (for eg completing the OAuth consent or installing a slack app to a workspace). The user must visit the browser to complete the process while you wait for the process to complete.

Available Services

Service	Modes	Description
slack	user, bot	Slack API access
github	user, app	GitHub API access
MCP servers	user, app	Any MCP server (mcp.<host>/<path>)
snowflake	user	Snowflake data access
Generic OAuth provider	user, app	Any OAuth 2.0 server registered via vercel connect create

For MCP servers, pass the full endpoint URL when registering (e.g. vercel connect create https://mcp.linear.app/mcp). The connector ID then takes the form mcp.<host>/<name> (for example mcp.linear.app/myagent).

Example: Send a Slack message using curl

TOKEN=$(vercel connect token <connector>)
curl -X POST https://slack.com/api/chat.postMessage \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channel": "C1234567890", "text": "Hello from Vercel Connect!"}'

2. 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("scl_abc123", {
  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!",
  }),
});

The SDK uses the user's Vercel OIDC token to authenticate. The user should have run vc env pull to pull the OIDC token env variables locally (or vc link pulls it automatically)

Eve agents — @vercel/connect/eve

When the project is built on Eve, prefer the connect helper over calling getToken directly inside connection definitions. The helper wires the full token / start-authorization / complete-authorization lifecycle into Eve's connection runtime, so a Vercel Connect-backed connection becomes a single declaration:

// 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("mcp.linear.app/myagent"),
});

Key points for the agent:

• Omit principalType for the default per-user OAuth flow, or set "app" for app-scoped tokens (no consent flow — fail terminally if not installed).
• Pass the connector id directly with connect("mcp.linear.app/myagent"), or use connect({ connector: "mcp.linear.app/myagent" }) 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 { slackRoute } from "eve/channels/slack";
import { connectSlackCredentials } from "@vercel/connect/eve";

export default slackRoute({
  credentials: connectSlackCredentials("slack/myagent"),
});

What the helper wires up:

• botToken: a function that calls getToken(connector, { subject: { type: "app" } }) on each inbound webhook, so token rotation, refresh, and multi-workspace tenancy are handled server-side.
• 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.

Use this whenever the project is on Eve + Vercel Connect — it's 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 (skipping its native GitHub App JWT exchange) and Vercel Connect handles rotation, refresh, and multi-installation tenancy server-side. 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 { githubRoute } from "eve/channels/github";
import { connectGitHubCredentials } from "@vercel/connect/eve";

export default githubRoute({
  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" — 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_API_KEY or LINEAR_WEBHOOK_SECRET env vars:

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

export default linearRoute({
  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" — 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.

3. HTTP API (for other languages)

For other languages, make HTTP requests directly to the Vercel Connect server. The request must be authenticated with the projec

---

Content truncated.