vercel-connect

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Vercel Connect Skill

Vercel Connect 技能

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.
Vercel Connect 可代表应用或用户安全获取用于访问第三方服务的限定范围令牌。它通过 Vercel API 使用 Vercel OIDC 令牌进行身份验证并兑换为 Vercel Connect 令牌。

When to Use Vercel Connect

何时使用 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
当你需要以下操作时,可使用 Vercel Connect:
  • 通过 Slack 发送消息(以机器人身份或代表用户)
  • 访问 GitHub 仓库或 API
  • 连接任何需要 OAuth 令牌或 API 凭证的第三方系统
  • 获取用于已验证 API 调用的令牌

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.
SDK 支持三种主体类型——根据操作主体选择:
  • user
    —— 代表特定终端用户执行操作(例如,以用户身份发送 Slack 消息)。需要用户
    id
    和可选的
    issuer
  • app
    —— 以应用自身身份执行操作(例如,以 Slack 机器人身份发送消息、应用级别的 GitHub 访问)。无需授权流程——如果未安装连接器,操作会直接失败。
  • jwt-bearer
    —— 针对接受调用方生成断言的连接器,采用 RFC 7523 JWT-bearer 交换方式。需传入
    sub
    (必填),以及可选的
    iss
    aud
    additionalClaims
    。当第三方期望你通过签名 JWT 而非交互式 OAuth 授权来证明主体身份时使用此模式。

Available Tools

可用工具

All tools have
--format=json
option for machine-readable output.
所有工具都支持
--format=json
选项,以生成机器可读的输出。

1. Vercel Connect CLI (for Bash/Shell)

1. Vercel Connect CLI(适用于 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:
bash
undefined
使用
vercel connect
CLI 进行命令行操作。使用
vercel connect --help
获取可用命令。用户需要先通过 Vercel CLI 进行身份验证,命令将在用户当前选中的 Vercel 团队范围内生效。例如,它将创建和列出当前选中的 Vercel 团队内的 Connect 连接器。
重要提示!请始终从将使用该连接的项目或代理文件夹(包含
package.json
/
vercel.json
的目录)中运行
vercel connect
命令。Vercel Connect 会读取本地项目上下文来自动配置连接——例如,选择合理的连接器名称和
uid
,设置项目对该连接的访问权限,配置 Webhook 和触发器。如果从仓库根目录或无关目录运行,将跳过此自动配置,你需要手动完成所有设置。如果用户从其他位置调用
vc connect
命令,请先切换到最近的匹配项目/代理文件夹(或传入
--cwd <DIR>
参数)。
示例命令:
bash
undefined

Create new Connect connector

创建新的 Connect 连接器

vercel connect create <service>
vercel connect create <service>

List existing Connect connectors

列出已有的 Connect 连接器

vercel connect list
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.
vercel connect token <connector> --subject user|app

重要提示!`vercel connect create` 和 `vercel connect token` 命令可能会打开浏览器让用户完成手动注册流程(例如,完成 OAuth 授权或向工作区安装 Slack 应用)。用户必须访问浏览器完成该流程,你需要等待流程结束。

Available Services

可用服务

ServiceModesDescription
slack
user, botSlack API access
github
user, appGitHub API access
MCP serversuser, appAny MCP server (
mcp.<host>/<path>
)
snowflake
userSnowflake data access
Generic OAuth provideruser, appAny 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
).
服务名称模式描述
slack
user, botSlack API 访问权限
github
user, appGitHub API 访问权限
MCP serversuser, app任意 MCP 服务器(
mcp.<host>/<path>
snowflake
userSnowflake 数据访问权限
Generic OAuth provideruser, app通过
vercel connect create
注册的任意 OAuth 2.0 服务器
对于 MCP 服务器,注册时需传入完整的端点 URL(例如
vercel connect create https://mcp.linear.app/mcp
)。连接器 ID 格式为
mcp.<host>/<name>
(例如
mcp.linear.app/myagent
)。

Example: Send a Slack message using curl

示例:使用 curl 发送 Slack 消息

bash
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!"}'
bash
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
)

2. JavaScript/TypeScript SDK (
@vercel/connect
)

For JavaScript/TypeScript code, use the
@vercel/connect
package directly:
typescript
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)
对于 JavaScript/TypeScript 代码,可直接使用
@vercel/connect
包:
typescript
import { getToken } from "@vercel/connect";

// 获取 Slack 机器人令牌
const token = await getToken("scl_abc123", {
  subject: { type: "app" }, // 如果以机器人身份发送消息,否则使用 "user"
});

// 使用令牌
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!",
  }),
});
SDK 使用用户的 Vercel OIDC 令牌进行身份验证。用户应运行
vc env pull
来拉取本地 OIDC 令牌环境变量(或
vc link
会自动拉取)

Eve agents —
@vercel/connect/eve

Eve 代理 ——
@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:
typescript
// 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.
当项目基于 Eve 构建时,建议在连接定义中使用
connect
助手,而非直接调用
getToken
。该助手会将完整的令牌/启动授权/完成授权生命周期接入 Eve 的连接运行时,因此基于 Vercel Connect 的连接只需单一声明:
typescript
// 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 工作区——问题、项目、周期和评论。",
  auth: connect("mcp.linear.app/myagent"),
});
代理相关要点:
  • 若使用默认的每用户 OAuth 流程,可省略
    principalType
    ;若要获取应用范围的令牌(无需授权流程——未安装则直接失败),请设置为
    "app"
  • 可直接传入连接器 ID 使用
    connect("mcp.linear.app/myagent")
    ,或在需要配置选项时使用
    connect({ connector: "mcp.linear.app/myagent" })
  • 如需指定范围、受众或
    authorizationDetails
    ,可通过
    tokenParams
    传入;如需自定义挑战提示,可传入
    instructions
    。两者均为可选参数。
  • eve
    是可选的对等依赖,因此
    @vercel/connect
    的其他部分(CLI、
    getToken
    等)对非 Eve 用户无影响。
Slack channel —
connectSlackCredentials
Slack 频道 ——
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:
typescript
// 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.
对于 Eve Slack 频道(
agent/channels/slack.ts
),请使用
@vercel/connect/eve
中的
connectSlackCredentials(connector)
。它会返回完整的
SlackChannelCredentials
对象——Vercel Connect 会处理机器人令牌和入站 Webhook 验证,因此你无需设置
SLACK_BOT_TOKEN
SLACK_SIGNING_SECRET
环境变量:
typescript
// agent/channels/slack.ts
import { slackRoute } from "eve/channels/slack";
import { connectSlackCredentials } from "@vercel/connect/eve";

export default slackRoute({
  credentials: connectSlackCredentials("slack/myagent"),
});
该助手的功能:
  • botToken
    :一个函数,会在每个入站 Webhook 调用时执行
    getToken(connector, { subject: { type: "app" } })
    ,因此令牌轮换、刷新和多工作区租户管理均由服务器端处理。
  • webhookVerifier
    :Vercel OIDC 验证器(
    vercelOidc()
    )。Vercel Connect 会将经过验证的 Slack Webhook 以签名的 Vercel OIDC 请求形式转发至你的应用;该助手会验证此签名,而非原始的 Slack 签名密钥。
只要项目基于 Eve + Vercel Connect,就建议使用此方法——只需一行代码即可处理出站消息和入站 Webhook 身份验证。
GitHub channel —
connectGitHubCredentials
GitHub 频道 ——
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:
typescript
// 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.
对于 Eve GitHub 频道(
agent/channels/github.ts
),请使用
@vercel/connect/eve
中的
connectGitHubCredentials(connector)
。它会返回完整的
GitHubChannelCredentials
对象——Eve 直接使用安装令牌(跳过其原生的 GitHub App JWT 交换),Vercel Connect 会在服务器端处理令牌轮换、刷新和多安装租户管理。你无需设置
GITHUB_APP_PRIVATE_KEY
GITHUB_APP_ID
GITHUB_INSTALLATION_ID
GITHUB_WEBHOOK_SECRET
环境变量:
typescript
// agent/channels/github.ts
import { githubRoute } from "eve/channels/github";
import { connectGitHubCredentials } from "@vercel/connect/eve";

export default githubRoute({
  credentials: connectGitHubCredentials("github/myagent"),
});
该助手的功能:
  • installationToken
    :一个函数,会执行
    getToken(connector, { subject: { type: "app" } })
    。该助手会将
    subject
    固定为
    "app"
    ——GitHub 安装令牌属于应用范围。
  • webhookVerifier
    :Vercel OIDC 验证器(
    vercelOidc()
    )。Vercel Connect 会将经过验证的 GitHub Webhook 以签名的 Vercel OIDC 请求形式转发至你的应用;该助手会验证此签名,而非原始的 GitHub Webhook 密钥。
Linear channel —
connectLinearCredentials
Linear 频道 ——
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:
typescript
// 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.
对于 Eve Linear 频道(
agent/channels/linear.ts
),请使用
@vercel/connect/eve
中的
connectLinearCredentials(connector)
。它会返回完整的
LinearChannelCredentials
对象——Vercel Connect 会管理 Linear 应用访问令牌和 Webhook 身份验证,因此你无需设置
LINEAR_API_KEY
LINEAR_WEBHOOK_SECRET
环境变量:
typescript
// agent/channels/linear.ts
import { linearRoute } from "eve/channels/linear";
import { connectLinearCredentials } from "@vercel/connect/eve";

export default linearRoute({
  credentials: connectLinearCredentials("linear/myagent"),
});
该助手的功能:
  • accessToken
    :一个函数,会执行
    getToken(connector, { subject: { type: "app" } })
    。该助手会将
    subject
    固定为
    "app"
    ——Linear 代理令牌属于应用范围。
  • webhookVerifier
    :Vercel OIDC 验证器(
    vercelOidc()
    )。Vercel Connect 会将经过验证的 Linear Webhook 以签名的 Vercel OIDC 请求形式转发至你的应用;该助手会验证此签名,而非原始的 Linear Webhook 密钥。

3. HTTP API (for other languages)

3. HTTP API(适用于其他语言)

For other languages, make HTTP requests directly to the Vercel Connect server. The request must be authenticated with the project's Vercel OIDC token (
VERCEL_OIDC_TOKEN
env var — pulled by
vc env pull
or injected at runtime):
bash
undefined
对于其他语言,可直接向 Vercel Connect 服务器发送 HTTP 请求。请求必须使用项目的 Vercel OIDC 令牌(
VERCEL_OIDC_TOKEN
环境变量——通过
vc env pull
拉取或运行时注入)进行身份验证:
bash
undefined

Get a token via HTTP

通过 HTTP 获取令牌

POST https://api.vercel.com/v1/connect/token/<connector> Authorization: Bearer <VERCEL_OIDC_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).
POST https://api.vercel.com/v1/connect/token/<connector> Authorization: Bearer <VERCEL_OIDC_TOKEN> Content-Type: application/json
{ "subject": { "type": "user", "id": "user_123" } }

响应为 JSON 格式,包含 `token` 字段(以及 `expiresAt`、`connector` 和其他元数据)。

Python Example

Python 示例

python
import os
import requests
python
import os
import requests

Get token from Vercel Connect

从 Vercel Connect 获取令牌

connect_response = requests.post( "https://api.vercel.com/v1/connect/token/slack1234", headers={"Authorization": f"Bearer {os.environ['VERCEL_OIDC_TOKEN']}"}, json={ "subject": {"type": "app"}, "scopes": ["chat:write"], }, ) token = connect_response.json()["token"]
connect_response = requests.post( "https://api.vercel.com/v1/connect/token/slack1234", headers={"Authorization": f"Bearer {os.environ['VERCEL_OIDC_TOKEN']}"}, json={ "subject": {"type": "app"}, "scopes": ["chat:write"], }, ) 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!"} )
undefined
slack_response = requests.post( "https://slack.com/api/chat.postMessage", headers={"Authorization": f"Bearer {token}"}, json={"channel": "C1234567890", "text": "Hello from Vercel Connect!"} )
undefined

4. BetterAuth and AuthJS support

4. BetterAuth 和 AuthJS 支持

When the app already uses Better Auth or Auth.js for end-user authentication, you can plug a Vercel Connect connector in as an OAuth provider instead of calling
getToken
directly. The
connect
helper on each subpath handles the token exchange so provider credentials stay in Vercel Connect rather than in framework config or env vars.
当应用已使用 Better AuthAuth.js 进行终端用户身份验证时,你可以将 Vercel Connect 连接器作为 OAuth 提供商接入,而非直接调用
getToken
。每个子路径下的
connect
助手会处理令牌交换,因此提供商凭证将保留在 Vercel Connect 中,而非框架配置或环境变量里。

Better Auth —
@vercel/connect/betterauth

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
:
typescript
import { genericOAuth } from "better-auth/plugins";
import { connect } from "@vercel/connect/betterauth";

genericOAuth({
  config: [connect({ providerId: "linear", connector: "linear/myagent" })],
});
可选对等依赖:
better-auth
。通过 Better Auth 的
genericOAuth
插件传入连接器。连接器 UID 可包含
/
(例如
linear/myagent
),且 Better Auth 还需要
providerId
typescript
import { genericOAuth } from "better-auth/plugins";
import { connect } from "@vercel/connect/betterauth";

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

Auth.js —
@vercel/connect/authjs

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
:
typescript
import { connect } from "@vercel/connect/authjs";

const providers = [connect({ id: "linear", connector: "linear/myagent" })];
可选对等依赖:
@auth/core
。将连接器作为
OAuth2Config
提供商使用。连接器 UID 可包含
/
(例如
linear/myagent
),且 Auth.js 还需要
id
typescript
import { connect } from "@vercel/connect/authjs";

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

Workflow

工作流程

All tools have
--json
option for machine-readable output.
Before running any
vercel connect
step below, make sure your shell cwd is the project or agent folder that will use the connection (see the CLI section above). Vercel Connect uses that context to auto-configure the project, so running from the right directory removes follow-up wiring work.
  1. Check existing Connect connectors: See if a required Connect connector is already present
    bash
    vercel connect list
    vercel connect token <connector>
Important! If more than one connector found, allow user to make the choice between them, or ask to create a new one
  1. Register: If the provider you need is not registered of if the user asked to create a new connector / app / bot, follow the instructions to register it (this may involve setting up credentials on browser in the third-party service and then registering them with Vercel Connect).
    bash
    vercel connect create <service> [--name <app-name>]
Important! Provide the most precise server URL for the service, including the complete connection URL (e.g.
https://mcp.linear.app/mcp
rather than just
linear
). Short service aliases may resolve to a default endpoint that does not match the transport or path the user actually wants. When in doubt, run
vercel connect create --help
to confirm which service names and URL forms are accepted before picking one.
Important! This command will give you a URL or directly open it to complete the registration process. User must visit that URL and follow the instructions to link their third-party account with Vercel Connect. The command will not complete until they finish the registration. The agent must clearly show the URL to the user and prompt them to complete the registration.
Important! Once
vercel connect create
completes, it will print a successful message. You must capture that connector ID for the next step.
Important! The
vercel connect create
command may open the browser so it's better to get the user approval before running it.
  1. Get token: Obtain a token for the provider you need: On CLI, you can get the token via
    bash
    vercel connect token <connector> [--subject <subject>]
The default subject is user. Use app for getting app scoped tokens. It's recommended to run this command with the
--yes
in case an re-authorization or installation is required. This will trigger the reauthorization flow for the user.
Important! Always put the token value into a variable and use the variable in the subsequent commands to avoid accidentally echoing the token in the terminal or logs. Avoid combining this command with other commands using
&&
. For example:
bash
TOKEN=$(vercel connect token)
Important! Try to reuse tokens as much as possible. If you already have a token with the required scopes, use it instead of requesting a new one, even when fewer scopes are needed. This will reduce friction for the user and avoid unnecessary authorization prompts.
When working with a JavaScript/TypeScript code, use the
@vercel/connect
package directly:
  1. Use token: Use the token to authenticate with the third-party service. For example:
typescript
import { getToken } from "@vercel/connect";

const token = await getToken(
  "connector-id",
  // Optional params:
  {
    subject: { ... },
  },
);
所有工具都支持
--json
选项,以生成机器可读的输出。
在运行以下任何
vercel connect
步骤之前,请确保你的 Shell 当前工作目录是将使用该连接的项目或代理文件夹(参见上文 CLI 部分)。Vercel Connect 会使用该上下文自动配置项目,因此从正确的目录运行可省去后续的手动设置工作。
  1. 检查已有的 Connect 连接器:查看所需的 Connect 连接器是否已存在
    bash
    vercel connect list
    vercel connect token <connector>
重要提示!如果找到多个连接器,请让用户选择其中一个,或询问是否要创建新的连接器/应用/机器人
  1. 注册:如果所需的提供商未注册,或用户要求创建新的连接器/应用/机器人,请按照说明进行注册(这可能涉及在第三方服务的浏览器中设置凭证,然后将其注册到 Vercel Connect)。
    bash
    vercel connect create <service> [--name <app-name>]
重要提示!请提供该服务最精确的服务器 URL,包括完整的连接 URL(例如
https://mcp.linear.app/mcp
,而非仅
linear
)。简短的服务别名可能会解析为默认端点,与用户实际需要的传输协议或路径不匹配。如有疑问,请先运行
vercel connect create --help
确认接受的服务名称和 URL 格式,再进行选择。
重要提示!该命令会提供一个 URL 或直接打开浏览器以完成注册流程。用户必须访问该 URL 并按照说明将其第三方账户与 Vercel Connect 关联。在用户完成注册前,命令不会结束。代理必须向用户清晰展示该 URL 并提示其完成注册。
重要提示!
vercel connect create
完成后,会打印成功消息。你必须记录该连接器 ID 以便下一步使用。
重要提示!
vercel connect create
命令可能会打开浏览器,因此最好先获得用户的批准再运行。
  1. 获取令牌:获取所需提供商的令牌: 在 CLI 中,可通过以下命令获取令牌:
    bash
    vercel connect token <connector> [--subject <subject>]
默认主体为 user。如需获取应用范围的令牌,请使用 app。建议添加
--yes
参数运行此命令,以防需要重新授权或安装。这将触发用户的重新授权流程。
重要提示!请始终将令牌值存入变量,并在后续命令中使用该变量,避免在终端或日志中意外泄露令牌。避免使用
&&
将此命令与其他命令组合。例如:
bash
TOKEN=$(vercel connect token)
重要提示!请尽可能重用令牌。如果你已有具备所需范围的令牌,即使所需范围更少,也请使用该令牌,而非请求新的令牌。这将减少用户的操作步骤,避免不必要的授权提示。
在 JavaScript/TypeScript 代码中,可直接使用
@vercel/connect
包:
  1. 使用令牌:使用令牌向第三方服务进行身份验证。 示例:
typescript
import { getToken } from "@vercel/connect";

const token = await getToken(
  "connector-id",
  // 可选参数:
  {
    subject: { ... },
  },
);