From e874c2307cc74c4e6ff3eb1780634506ace7c741 Mon Sep 17 00:00:00 2001 From: Jathin Pranav Singaraju Date: Thu, 28 May 2026 13:48:14 -0700 Subject: [PATCH 1/7] feat(skills): add vercel-connect skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a Claude skill for Vercel Connect — guides agents through the CLI workflow (`vercel connect create/list/token`), the @vercel/connect SDK (getToken, /ash subpath, connectSlackCredentials), and the HTTP API for non-JS callers. Source: ported from vercel/connect's skills/vercel-connect/SKILL.md, with frontmatter enriched to match vercel-plugin's pattern (metadata.priority, docs, importPatterns, bashPatterns, promptSignals, retrieval, chainTo). The @vercel/connect package itself is being moved to vercel/vercel in a companion PR: https://github.com/vercel/vercel/pull/16462 Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/vercel-connect/SKILL.md | 317 +++++++++++++++++++++++++++++++++ 1 file changed, 317 insertions(+) create mode 100644 skills/vercel-connect/SKILL.md diff --git a/skills/vercel-connect/SKILL.md b/skills/vercel-connect/SKILL.md new file mode 100644 index 0000000..f7988dd --- /dev/null +++ b/skills/vercel-connect/SKILL.md @@ -0,0 +1,317 @@ +--- +name: vercel-connect +description: Vercel Connect expert guidance — securely obtain scoped OAuth tokens for third-party services (Slack, GitHub, Linear, generic OAuth) on behalf of apps or users via Vercel OIDC. Use when wiring up third-party API access, sending Slack messages, accessing GitHub APIs, or building Ash agent connections. +metadata: + priority: 5 + docs: + - "https://vercel.com/docs/connect" + sitemap: "https://vercel.com/sitemap/docs.xml" + pathPatterns: + - 'agent/connections/**' + - 'agent/channels/**' + importPatterns: + - '@vercel/connect' + - '@vercel/connect/ash' + - '@vercel/connect/authjs' + - '@vercel/connect/betterauth' + bashPatterns: + - '\bvercel\s+connect\b' + - '\bvc\s+connect\b' + - '\bnpm\s+(install|i|add)\s+[^\n]*@vercel/connect\b' + - '\bpnpm\s+(install|i|add)\s+[^\n]*@vercel/connect\b' + - '\bbun\s+(install|i|add)\s+[^\n]*@vercel/connect\b' + - '\byarn\s+add\s+[^\n]*@vercel/connect\b' + promptSignals: + phrases: + - "vercel connect" + - "slack token" + - "slack bot token" + - "post to slack" + - "send slack message" + - "github oauth token" + - "linear oauth" + - "oauth token for" + - "third-party token" + - "connect to slack" + - "connect to github" + allOf: + - [slack, token] + - [github, token] + - [oauth, token] + anyOf: + - "vercel connect" + - "@vercel/connect" + - "oauth" + noneOf: + - "supabase auth" + - "clerk" + - "auth0" + minScore: 6 +retrieval: + aliases: + - vercel connect + - oauth helper + - third-party tokens + - connect sdk + intents: + - get slack token + - get github oauth token + - wire up third-party oauth + - add slack channel to agent + - connect to oauth provider + - obtain api credentials + entities: + - Vercel Connect + - getToken + - "@vercel/connect" + - OAuth + - Slack + - GitHub + - Ash + - connector + examples: + - send a slack message from my app + - get a github oauth token + - wire up Linear in my Ash agent +chainTo: + - + pattern: "from\\s+['\"]@vercel/connect/ash['\"]" + targetSkill: vercel-connect + message: 'Ash + Vercel Connect import detected — loading Vercel Connect guidance for the connect() helper and Slack channel patterns.' + - + pattern: 'SLACK_(BOT|SIGNING)_(TOKEN|SECRET)|SLACK_WEBHOOK_URL' + targetSkill: vercel-connect + message: 'Hand-managed Slack secrets detected — use Vercel Connect + connectSlackCredentials() to remove the need for SLACK_BOT_TOKEN/SLACK_SIGNING_SECRET env vars.' + skipIfFileContains: 'connectSlackCredentials|@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 + +Some tokens allow user and bot modes. The difference is important. When the goal is to perform actions on behalf of a user (e.g., post a message to a channel as the user), you need a user token. When the goal is to perform actions as a bot (e.g., post a message to a channel as a bot), you need a bot token. Some providers may also support app tokens for application-level access. + +## 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 `). + +Example commands: + +```bash +# Create new Connect connector +vercel connect create + +# List existing Connect connectors +vercel connect list + +# Get token +vercel connect token --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 Providers + +| Provider | Modes | Description | +| -------- | --------- | ----------------- | +| `slack` | user, bot | Slack API access | +| `github` | user, app | GitHub API access | + +And many more, including generic OAuth providers. + +#### Example: Send a Slack message using curl + +```bash +TOKEN=$(vercel connect token ) +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: + +```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) + +#### Ash agents — `@vercel/connect/ash` + +When the project is built on [Ash](https://github.com/vercel/ash), prefer the `connect` helper over calling `getToken` directly inside connection definitions. The helper wires the full token / start-authorization / complete-authorization lifecycle into Ash's connection runtime, so a Vercel Connect-backed connection becomes a single declaration: + +```typescript +// agent/connections/linear.ts +import { defineMcpClientConnection } from "experimental-ash/connections"; +import { connect } from "@vercel/connect/ash"; + +export default defineMcpClientConnection({ + url: "https://mcp.linear.app/sse", + description: "Linear workspace — issues, projects, cycles, and comments.", + auth: connect("linear"), +}); +``` + +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("linear")`, or use `connect({ connector: "linear" })` when you need options. +- For scopes, audiences, or `authorizationDetails`, pass them through `tokenParams`. For a custom challenge prompt, pass `instructions`. Both are optional. +- `experimental-ash` is an optional peer dependency, so the rest of `@vercel/connect` (CLI, `getToken`, etc.) is unaffected for non-Ash consumers. + +##### Slack channel — `connectSlackCredentials` + +For Ash Slack channels (`agent/channels/slack.ts`), use `connectSlackCredentials(connector)` from `@vercel/connect/ash`. 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 "experimental-ash/channels/slack"; +import { connectSlackCredentials } from "@vercel/connect/ash"; + +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 Ash + Vercel Connect — it's the one-liner for both outbound posts and inbound webhook auth. + +### 3. HTTP API (for other languages) + +For other languages, make HTTP requests directly to the Vercel Connect server: + +```bash +# Get a token via HTTP +POST https://api.vercel.com/v1/connect/token/ +Content-Type: application/json + +``` + +#### Python Example + +```python +import requests + +# Get token from Vercel Connect +connect_response = requests.post( + "https://api.vercel.com/v1/connect/token/slack1234", + json={ + "scopes": ["chat:write"] + } +) +token = connect_response.json()["accessToken"] + +# 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!"} +) +``` + +## 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 + ``` + +Important! If more than one connector found, allow user to make the choice between them, or ask to create a new one + +2. **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 [--name ] + ``` + +Important! Provide the most precise server URL for the provider, including the complete connection URL (e.g. `https://mcp.linear.app/sse` rather than just `linear`). Short provider 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 provider 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 the register-token completes, it will print a successful message. You must capture that connector ID for the next step. + +Important! The register-token command may open the browser so it's better to get the user approval before running it. + +3. **Get token**: Obtain a token for the provider you need: + On CLI, you can get the token via + + ```bash + vercel connect token [--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: + +4. **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: { ... }, + }, +); +``` From 17b98cdfa24ddde99aa343aa3079eebff63338a5 Mon Sep 17 00:00:00 2001 From: Jathin Pranav Singaraju Date: Thu, 28 May 2026 13:51:47 -0700 Subject: [PATCH 2/7] docs(ecosystem): add vercel-connect to ecosystem graph MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The validate script requires every skills/ directory to have a matching ⤳ skill: reference in vercel.md's ecosystem graph. Adds a VERCEL CONNECT block under Security alongside AUTHENTICATION INTEGRATIONS, listing the CLI / SDK / HTTP API integration paths and OIDC + Ash dependencies. Co-Authored-By: Claude Opus 4.7 (1M context) --- vercel.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/vercel.md b/vercel.md index 1f0e418..ad6da7d 100644 --- a/vercel.md +++ b/vercel.md @@ -457,6 +457,25 @@ AUTHENTICATION INTEGRATIONS ⤳ skill: auth ↔ Sign in with Vercel (Vercel OAuth) ``` +``` +VERCEL CONNECT ⤳ skill: vercel-connect 📖 docs: https://vercel.com/docs/connect +├── Purpose: Scoped OAuth tokens for third-party services +│ ⊃ Slack (user / bot tokens for messaging, channel access) +│ ⊃ GitHub (user / app tokens for repo and API access) +│ ⊃ Linear, generic OAuth providers +│ +├── Integration paths +│ ⊃ Vercel CLI (vercel connect create/list/token) +│ ⊃ @vercel/connect SDK (getToken) +│ ⊃ @vercel/connect/ash (connect() helper, connectSlackCredentials()) +│ ⊃ HTTP API (for non-JS callers) +│ +└── Integrations + ↔ Vercel OIDC (token exchange uses OIDC for authentication) + ↔ Vercel Agent / Ash (declarative connection wiring) + ⇢ replaces hand-managed SLACK_BOT_TOKEN / SLACK_SIGNING_SECRET env vars +``` + --- ## 7. CLI & API From 0a07c50faf0d21e75fe53cd75f54d30b5d5ac496 Mon Sep 17 00:00:00 2001 From: Jathin Pranav Singaraju Date: Thu, 28 May 2026 13:54:44 -0700 Subject: [PATCH 3/7] chore: regenerate skill-catalog with vercel-connect Run scripts/generate-catalog.ts to include the new vercel-connect skill in generated/skill-catalog.md. The validate script requires the catalog to list every skill in skills/. Co-Authored-By: Claude Opus 4.7 (1M context) --- generated/skill-catalog.md | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/generated/skill-catalog.md b/generated/skill-catalog.md index 81a1829..5c0bbbc 100644 --- a/generated/skill-catalog.md +++ b/generated/skill-catalog.md @@ -1,8 +1,8 @@ # Skill Catalog > Auto-generated by `scripts/generate-catalog.ts` — do not edit manually. -> Generated: 2026-05-19T03:50:40.894Z -> Skills: 26 +> Generated: 2026-05-28T20:54:40.376Z +> Skills: 27 ## Table of Contents @@ -35,6 +35,7 @@ | `runtime-cache` | 6 | 4 | 4 | 0 | | `shadcn` | 6 | 7 | 6 | 0 | | `nextjs` | 5 | 15 | 7 | 0 | +| `vercel-connect` | 5 | 2 | 6 | 4 | | `react-best-practices` | 4 | 8 | 0 | 2 | | `turbopack` | 4 | 1 | 2 | 0 | | `vercel-agent` | 4 | 6 | 1 | 0 | @@ -730,6 +731,26 @@ - `bun run dev` (bash) - `npx create-next-app` (bash) +#### `vercel-connect` (priority 5) + +**Path patterns:** +- `agent/connections/**` +- `agent/channels/**` + +**Bash patterns:** +- `\bvercel\s+connect\b` +- `\bvc\s+connect\b` +- `\bnpm\s+(install|i|add)\s+[^\n]*@vercel/connect\b` +- `\bpnpm\s+(install|i|add)\s+[^\n]*@vercel/connect\b` +- `\bbun\s+(install|i|add)\s+[^\n]*@vercel/connect\b` +- `\byarn\s+add\s+[^\n]*@vercel/connect\b` + +**Import patterns:** +- `@vercel/connect` +- `@vercel/connect/ash` +- `@vercel/connect/authjs` +- `@vercel/connect/betterauth` + #### `react-best-practices` (priority 4) **Path patterns:** @@ -893,7 +914,7 @@ Shows which skills compete on shared bash commands. **Priority 6:** `auth`, `deployments-cicd`, `next-cache-components`, `next-forge`, `next-upgrade`, `routing-middleware`, `runtime-cache`, `shadcn` -**Priority 5:** `nextjs` +**Priority 5:** `nextjs`, `vercel-connect` **Priority 4:** `react-best-practices`, `turbopack`, `vercel-agent`, `vercel-cli`, `vercel-sandbox` From 34c200253a55c4555f1efd444ad52ed60626aced Mon Sep 17 00:00:00 2001 From: Jathin Pranav Singaraju Date: Thu, 28 May 2026 13:54:54 -0700 Subject: [PATCH 4/7] chore: regenerate skill-manifest with vercel-connect MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Companion to the catalog regen — generate-catalog also refreshed the manifest with 142 lines of vercel-connect entries (trigger patterns, retrieval metadata, chainTo). Co-Authored-By: Claude Opus 4.7 (1M context) --- generated/skill-manifest.json | 143 +++++++++++++++++++++++++++++++++- 1 file changed, 142 insertions(+), 1 deletion(-) diff --git a/generated/skill-manifest.json b/generated/skill-manifest.json index a0b8057..8c8d142 100644 --- a/generated/skill-manifest.json +++ b/generated/skill-manifest.json @@ -1,5 +1,5 @@ { - "generatedAt": "2026-05-19T03:50:40.184Z", + "generatedAt": "2026-05-28T20:54:41.055Z", "version": 2, "skills": { "vercel-agent": { @@ -1396,6 +1396,147 @@ "examples": [] } }, + "vercel-connect": { + "priority": 5, + "summary": "", + "docs": [ + "https://vercel.com/docs/connect" + ], + "sitemap": "https://vercel.com/sitemap/docs.xml", + "pathPatterns": [ + "agent/connections/**", + "agent/channels/**" + ], + "bashPatterns": [ + "\\bvercel\\s+connect\\b", + "\\bvc\\s+connect\\b", + "\\bnpm\\s+(install|i|add)\\s+[^\\n]*@vercel/connect\\b", + "\\bpnpm\\s+(install|i|add)\\s+[^\\n]*@vercel/connect\\b", + "\\bbun\\s+(install|i|add)\\s+[^\\n]*@vercel/connect\\b", + "\\byarn\\s+add\\s+[^\\n]*@vercel/connect\\b" + ], + "importPatterns": [ + "@vercel/connect", + "@vercel/connect/ash", + "@vercel/connect/authjs", + "@vercel/connect/betterauth" + ], + "bodyPath": "skills/vercel-connect/SKILL.md", + "pathRegexSources": [ + "^agent\\/connections\\/.*$", + "^agent\\/channels\\/.*$" + ], + "bashRegexSources": [ + "\\bvercel\\s+connect\\b", + "\\bvc\\s+connect\\b", + "\\bnpm\\s+(install|i|add)\\s+[^\\n]*@vercel/connect\\b", + "\\bpnpm\\s+(install|i|add)\\s+[^\\n]*@vercel/connect\\b", + "\\bbun\\s+(install|i|add)\\s+[^\\n]*@vercel/connect\\b", + "\\byarn\\s+add\\s+[^\\n]*@vercel/connect\\b" + ], + "importRegexSources": [ + { + "source": "(?:from\\s+|require\\s*\\(\\s*|import\\s*\\(\\s*)['\"]@vercel\\/connect(?:\\/[^'\"]*)?['\"]", + "flags": "m" + }, + { + "source": "(?:from\\s+|require\\s*\\(\\s*|import\\s*\\(\\s*)['\"]@vercel\\/connect\\/ash(?:\\/[^'\"]*)?['\"]", + "flags": "m" + }, + { + "source": "(?:from\\s+|require\\s*\\(\\s*|import\\s*\\(\\s*)['\"]@vercel\\/connect\\/authjs(?:\\/[^'\"]*)?['\"]", + "flags": "m" + }, + { + "source": "(?:from\\s+|require\\s*\\(\\s*|import\\s*\\(\\s*)['\"]@vercel\\/connect\\/betterauth(?:\\/[^'\"]*)?['\"]", + "flags": "m" + } + ], + "chainTo": [ + { + "pattern": "from\\\\s+['\\\"]@vercel/connect/ash['\\\"]", + "targetSkill": "vercel-connect", + "message": "Ash + Vercel Connect import detected — loading Vercel Connect guidance for the connect() helper and Slack channel patterns." + }, + { + "pattern": "SLACK_(BOT|SIGNING)_(TOKEN|SECRET)|SLACK_WEBHOOK_URL", + "targetSkill": "vercel-connect", + "message": "Hand-managed Slack secrets detected — use Vercel Connect + connectSlackCredentials() to remove the need for SLACK_BOT_TOKEN/SLACK_SIGNING_SECRET env vars.", + "skipIfFileContains": "connectSlackCredentials|@vercel/connect" + } + ], + "promptSignals": { + "phrases": [ + "vercel connect", + "slack token", + "slack bot token", + "post to slack", + "send slack message", + "github oauth token", + "linear oauth", + "oauth token for", + "third-party token", + "connect to slack", + "connect to github" + ], + "allOf": [ + [ + "slack", + "token" + ], + [ + "github", + "token" + ], + [ + "oauth", + "token" + ] + ], + "anyOf": [ + "vercel connect", + "@vercel/connect", + "oauth" + ], + "noneOf": [ + "supabase auth", + "clerk", + "auth0" + ], + "minScore": 6 + }, + "retrieval": { + "aliases": [ + "vercel connect", + "oauth helper", + "third-party tokens", + "connect sdk" + ], + "intents": [ + "get slack token", + "get github oauth token", + "wire up third-party oauth", + "add slack channel to agent", + "connect to oauth provider", + "obtain api credentials" + ], + "entities": [ + "Vercel Connect", + "getToken", + "@vercel/connect", + "OAuth", + "Slack", + "GitHub", + "Ash", + "connector" + ], + "examples": [ + "send a slack message from my app", + "get a github oauth token", + "wire up Linear in my Ash agent" + ] + } + }, "verification": { "priority": 7, "summary": "Verify full user story: browser + server + data flow + env", From 3a1559a70f8bd1c46b61b874234c6eebd7f5ed40 Mon Sep 17 00:00:00 2001 From: Jathin Pranav Singaraju Date: Thu, 28 May 2026 16:43:59 -0700 Subject: [PATCH 5/7] fix(skills): address vercel-connect review feedback from dvoytenko - Rename `` placeholder to `` in CLI examples - Expand Available Services table: add MCP servers, Snowflake, Salesforce, and generic OAuth alongside Slack and GitHub - Update Ash example: use `/mcp` endpoint (not `/sse`) and the correct URL-style connector ID (`mcp.linear.app/myagent` rather than `linear`) - Update Workflow URL example to `/mcp` - Expand frontmatter retrieval + promptSignals with MCP, Snowflake, and Salesforce terms so prompts like "connect to mcp server" trigger the skill - Regenerate skill-manifest.json + skill-catalog.md Co-Authored-By: Claude Opus 4.7 (1M context) --- generated/skill-catalog.md | 2 +- generated/skill-manifest.json | 36 ++++++++++++++++++++----- skills/vercel-connect/SKILL.md | 48 +++++++++++++++++++++++++--------- 3 files changed, 66 insertions(+), 20 deletions(-) diff --git a/generated/skill-catalog.md b/generated/skill-catalog.md index 5c0bbbc..0088dae 100644 --- a/generated/skill-catalog.md +++ b/generated/skill-catalog.md @@ -1,7 +1,7 @@ # Skill Catalog > Auto-generated by `scripts/generate-catalog.ts` — do not edit manually. -> Generated: 2026-05-28T20:54:40.376Z +> Generated: 2026-05-28T23:43:55.508Z > Skills: 27 ## Table of Contents diff --git a/generated/skill-manifest.json b/generated/skill-manifest.json index 8c8d142..38eb036 100644 --- a/generated/skill-manifest.json +++ b/generated/skill-manifest.json @@ -1,5 +1,5 @@ { - "generatedAt": "2026-05-28T20:54:41.055Z", + "generatedAt": "2026-05-28T23:43:56.362Z", "version": 2, "skills": { "vercel-agent": { @@ -1477,7 +1477,12 @@ "oauth token for", "third-party token", "connect to slack", - "connect to github" + "connect to github", + "connect to mcp", + "mcp connection", + "mcp server", + "snowflake connection", + "salesforce connection" ], "allOf": [ [ @@ -1491,12 +1496,21 @@ [ "oauth", "token" + ], + [ + "mcp", + "connect" + ], + [ + "mcp", + "server" ] ], "anyOf": [ "vercel connect", "@vercel/connect", - "oauth" + "oauth", + "mcp" ], "noneOf": [ "supabase auth", @@ -1510,7 +1524,8 @@ "vercel connect", "oauth helper", "third-party tokens", - "connect sdk" + "connect sdk", + "mcp connector" ], "intents": [ "get slack token", @@ -1518,7 +1533,11 @@ "wire up third-party oauth", "add slack channel to agent", "connect to oauth provider", - "obtain api credentials" + "obtain api credentials", + "connect to mcp server", + "set up mcp connection", + "add snowflake connection", + "add salesforce connection" ], "entities": [ "Vercel Connect", @@ -1527,13 +1546,18 @@ "OAuth", "Slack", "GitHub", + "MCP", + "Snowflake", + "Salesforce", "Ash", "connector" ], "examples": [ "send a slack message from my app", "get a github oauth token", - "wire up Linear in my Ash agent" + "wire up Linear in my Ash agent", + "connect my agent to a MCP server", + "add Snowflake credentials to my project" ] } }, diff --git a/skills/vercel-connect/SKILL.md b/skills/vercel-connect/SKILL.md index f7988dd..b5bb108 100644 --- a/skills/vercel-connect/SKILL.md +++ b/skills/vercel-connect/SKILL.md @@ -1,6 +1,6 @@ --- name: vercel-connect -description: Vercel Connect expert guidance — securely obtain scoped OAuth tokens for third-party services (Slack, GitHub, Linear, generic OAuth) on behalf of apps or users via Vercel OIDC. Use when wiring up third-party API access, sending Slack messages, accessing GitHub APIs, or building Ash agent connections. +description: Vercel Connect expert guidance — securely obtain scoped OAuth tokens for third-party services (Slack, GitHub, MCP servers, OAuth, Snowflake, Salesforce) on behalf of apps or users via Vercel OIDC. Use when wiring up third-party API access, connecting to MCP servers, sending Slack messages, accessing GitHub APIs, or building Ash agent connections. metadata: priority: 5 docs: @@ -34,14 +34,22 @@ metadata: - "third-party token" - "connect to slack" - "connect to github" + - "connect to mcp" + - "mcp connection" + - "mcp server" + - "snowflake connection" + - "salesforce connection" allOf: - [slack, token] - [github, token] - [oauth, token] + - [mcp, connect] + - [mcp, server] anyOf: - "vercel connect" - "@vercel/connect" - "oauth" + - "mcp" noneOf: - "supabase auth" - "clerk" @@ -53,6 +61,7 @@ retrieval: - oauth helper - third-party tokens - connect sdk + - mcp connector intents: - get slack token - get github oauth token @@ -60,6 +69,10 @@ retrieval: - add slack channel to agent - connect to oauth provider - obtain api credentials + - connect to mcp server + - set up mcp connection + - add snowflake connection + - add salesforce connection entities: - Vercel Connect - getToken @@ -67,12 +80,17 @@ retrieval: - OAuth - Slack - GitHub + - MCP + - Snowflake + - Salesforce - Ash - connector examples: - send a slack message from my app - get a github oauth token - wire up Linear in my Ash agent + - connect my agent to a MCP server + - add Snowflake credentials to my project chainTo: - pattern: "from\\s+['\"]@vercel/connect/ash['\"]" @@ -118,7 +136,7 @@ Example commands: ```bash # Create new Connect connector -vercel connect create +vercel connect create # List existing Connect connectors vercel connect list @@ -129,14 +147,18 @@ vercel connect token --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 Providers +#### Available Services -| Provider | Modes | Description | -| -------- | --------- | ----------------- | -| `slack` | user, bot | Slack API access | -| `github` | user, app | GitHub API access | +| Service | Modes | Description | +| ---------------------- | ---------- | ------------------------------------------ | +| `slack` | user, bot | Slack API access | +| `github` | user, app | GitHub API access | +| MCP servers | user, app | Any MCP server (`mcp./`) | +| `snowflake` | user | Snowflake data access | +| `salesforce` | user | Salesforce API access | +| Generic OAuth provider | user, app | Any OAuth 2.0 server registered via `vercel connect create` | -And many more, including generic OAuth providers. +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./` (for example `mcp.linear.app/myagent`). #### Example: Send a Slack message using curl @@ -186,16 +208,16 @@ import { defineMcpClientConnection } from "experimental-ash/connections"; import { connect } from "@vercel/connect/ash"; export default defineMcpClientConnection({ - url: "https://mcp.linear.app/sse", + url: "https://mcp.linear.app/mcp", description: "Linear workspace — issues, projects, cycles, and comments.", - auth: connect("linear"), + 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("linear")`, or use `connect({ connector: "linear" })` when you need options. +- 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. - `experimental-ash` is an optional peer dependency, so the rest of `@vercel/connect` (CLI, `getToken`, etc.) is unaffected for non-Ash consumers. @@ -271,10 +293,10 @@ Important! If more than one connector found, allow user to make the choice betwe 2. **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 [--name ] + vercel connect create [--name ] ``` -Important! Provide the most precise server URL for the provider, including the complete connection URL (e.g. `https://mcp.linear.app/sse` rather than just `linear`). Short provider 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 provider names and URL forms are accepted before picking one. +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. From 22f96ce25f3a57a24bef9c7cbd83059fc63c43ba Mon Sep 17 00:00:00 2001 From: Jathin Pranav Singaraju Date: Tue, 9 Jun 2026 12:32:15 -0700 Subject: [PATCH 6/7] fix(skills): strip Ash, fix HTTP auth + Python field + subject types MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Strip Ash from the vercel-connect skill (the @vercel/connect package renamed Ash -> Eve in vercel/vercel#16541 and is moving away from adapter-specific guidance in this skill). Frontmatter: - Remove importPatterns `@vercel/connect/ash` - Remove pathPatterns `agent/connections/**` and `agent/channels/**` - Remove retrieval.entities `Ash`, retrieval.examples / intents referencing Ash agents - Remove the two chainTo rules tied to Ash imports and SLACK_BOT_TOKEN / SLACK_SIGNING_SECRET (the latter pointed at the Ash-only `connectSlackCredentials` helper) - Drop "building Ash agent connections" from description Body: - Delete `#### Ash agents — @vercel/connect/ash` section - Delete `##### Slack channel — connectSlackCredentials` subsection Factual fixes against vercel/vercel:packages/connect/ (current `main`): 1. HTTP API Python example: response field is `token`, not `accessToken` (src/token.ts:51-69). 2. HTTP API examples now include the required `Authorization: Bearer ` header — without it the request 401s (src/token.ts:148-158). 3. "Modes of tokens" now lists all three subject types: `user`, `app`, and `jwt-bearer`. The third was added in vercel/vercel#16520 (src/token.ts:4-29) and was missing from the skill. 4. Workflow step 2: "register-token" terminology replaced with the actual CLI command name `vercel connect create`. No restructure, no new API surface added (revokeToken, /ai-sdk, /mcp, /betterauth, /authjs, startAuthorization, typed errors are intentionally out of scope for this update). Net: -69 / +19 lines. Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/vercel-connect/SKILL.md | 88 ++++++++-------------------------- 1 file changed, 19 insertions(+), 69 deletions(-) diff --git a/skills/vercel-connect/SKILL.md b/skills/vercel-connect/SKILL.md index b5bb108..2be1c6a 100644 --- a/skills/vercel-connect/SKILL.md +++ b/skills/vercel-connect/SKILL.md @@ -1,17 +1,13 @@ --- name: vercel-connect -description: Vercel Connect expert guidance — securely obtain scoped OAuth tokens for third-party services (Slack, GitHub, MCP servers, OAuth, Snowflake, Salesforce) on behalf of apps or users via Vercel OIDC. Use when wiring up third-party API access, connecting to MCP servers, sending Slack messages, accessing GitHub APIs, or building Ash agent connections. +description: Vercel Connect expert guidance — securely obtain scoped OAuth tokens for third-party services (Slack, GitHub, MCP servers, OAuth, Snowflake, Salesforce) on behalf of apps or users via Vercel OIDC. Use when wiring up third-party API access, connecting to MCP servers, sending Slack messages, or accessing GitHub APIs. metadata: priority: 5 docs: - "https://vercel.com/docs/connect" sitemap: "https://vercel.com/sitemap/docs.xml" - pathPatterns: - - 'agent/connections/**' - - 'agent/channels/**' importPatterns: - '@vercel/connect' - - '@vercel/connect/ash' - '@vercel/connect/authjs' - '@vercel/connect/betterauth' bashPatterns: @@ -66,7 +62,6 @@ retrieval: - get slack token - get github oauth token - wire up third-party oauth - - add slack channel to agent - connect to oauth provider - obtain api credentials - connect to mcp server @@ -83,24 +78,12 @@ retrieval: - MCP - Snowflake - Salesforce - - Ash - connector examples: - send a slack message from my app - get a github oauth token - - wire up Linear in my Ash agent - connect my agent to a MCP server - add Snowflake credentials to my project -chainTo: - - - pattern: "from\\s+['\"]@vercel/connect/ash['\"]" - targetSkill: vercel-connect - message: 'Ash + Vercel Connect import detected — loading Vercel Connect guidance for the connect() helper and Slack channel patterns.' - - - pattern: 'SLACK_(BOT|SIGNING)_(TOKEN|SECRET)|SLACK_WEBHOOK_URL' - targetSkill: vercel-connect - message: 'Hand-managed Slack secrets detected — use Vercel Connect + connectSlackCredentials() to remove the need for SLACK_BOT_TOKEN/SLACK_SIGNING_SECRET env vars.' - skipIfFileContains: 'connectSlackCredentials|@vercel/connect' --- # Vercel Connect Skill @@ -120,7 +103,11 @@ Use Vercel Connect when you need to: ## Modes of tokens -Some tokens allow user and bot modes. The difference is important. When the goal is to perform actions on behalf of a user (e.g., post a message to a channel as the user), you need a user token. When the goal is to perform actions as a bot (e.g., post a message to a channel as a bot), you need a bot token. Some providers may also support app tokens for application-level access. +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 @@ -198,74 +185,37 @@ const response = await fetch("https://slack.com/api/chat.postMessage", { 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) -#### Ash agents — `@vercel/connect/ash` - -When the project is built on [Ash](https://github.com/vercel/ash), prefer the `connect` helper over calling `getToken` directly inside connection definitions. The helper wires the full token / start-authorization / complete-authorization lifecycle into Ash's connection runtime, so a Vercel Connect-backed connection becomes a single declaration: - -```typescript -// agent/connections/linear.ts -import { defineMcpClientConnection } from "experimental-ash/connections"; -import { connect } from "@vercel/connect/ash"; - -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. -- `experimental-ash` is an optional peer dependency, so the rest of `@vercel/connect` (CLI, `getToken`, etc.) is unaffected for non-Ash consumers. - -##### Slack channel — `connectSlackCredentials` - -For Ash Slack channels (`agent/channels/slack.ts`), use `connectSlackCredentials(connector)` from `@vercel/connect/ash`. 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 "experimental-ash/channels/slack"; -import { connectSlackCredentials } from "@vercel/connect/ash"; - -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 Ash + Vercel Connect — it's the one-liner for both outbound posts and inbound webhook auth. - ### 3. HTTP API (for other languages) -For other languages, make HTTP requests directly to the Vercel Connect server: +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 # Get a token via HTTP POST https://api.vercel.com/v1/connect/token/ +Authorization: Bearer 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 ```python +import os import requests # Get token from Vercel Connect connect_response = requests.post( "https://api.vercel.com/v1/connect/token/slack1234", + headers={"Authorization": f"Bearer {os.environ['VERCEL_OIDC_TOKEN']}"}, json={ - "scopes": ["chat:write"] - } + "subject": {"type": "app"}, + "scopes": ["chat:write"], + }, ) -token = connect_response.json()["accessToken"] +token = connect_response.json()["token"] # Use the token slack_response = requests.post( @@ -300,9 +250,9 @@ Important! Provide the most precise server URL for the service, including the co 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 the register-token completes, it will print a successful message. You must capture that connector ID for the next step. +Important! Once `vercel connect create` completes, it will print a successful message. You must capture that connector ID for the next step. -Important! The register-token command may open the browser so it's better to get the user approval before running it. +Important! The `vercel connect create` command may open the browser so it's better to get the user approval before running it. 3. **Get token**: Obtain a token for the provider you need: On CLI, you can get the token via From e0021daa6a6d404f018d010c423aac49cf7d7167 Mon Sep 17 00:00:00 2001 From: Jathin Pranav Singaraju Date: Tue, 9 Jun 2026 12:39:25 -0700 Subject: [PATCH 7/7] fix(skills): remove Salesforce from vercel-connect skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per @dvoytenko review on #94 — Salesforce isn't a supported Connect service yet, drop it for now. Removed: - Services table row - description copy - retrieval.entities, retrieval.intents, promptSignals.phrases Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/vercel-connect/SKILL.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/skills/vercel-connect/SKILL.md b/skills/vercel-connect/SKILL.md index 2be1c6a..8f121db 100644 --- a/skills/vercel-connect/SKILL.md +++ b/skills/vercel-connect/SKILL.md @@ -1,6 +1,6 @@ --- name: vercel-connect -description: Vercel Connect expert guidance — securely obtain scoped OAuth tokens for third-party services (Slack, GitHub, MCP servers, OAuth, Snowflake, Salesforce) on behalf of apps or users via Vercel OIDC. Use when wiring up third-party API access, connecting to MCP servers, sending Slack messages, or accessing GitHub APIs. +description: Vercel Connect expert guidance — securely obtain scoped OAuth tokens for third-party services (Slack, GitHub, MCP servers, OAuth, Snowflake) on behalf of apps or users via Vercel OIDC. Use when wiring up third-party API access, connecting to MCP servers, sending Slack messages, or accessing GitHub APIs. metadata: priority: 5 docs: @@ -34,7 +34,6 @@ metadata: - "mcp connection" - "mcp server" - "snowflake connection" - - "salesforce connection" allOf: - [slack, token] - [github, token] @@ -67,7 +66,6 @@ retrieval: - connect to mcp server - set up mcp connection - add snowflake connection - - add salesforce connection entities: - Vercel Connect - getToken @@ -77,7 +75,6 @@ retrieval: - GitHub - MCP - Snowflake - - Salesforce - connector examples: - send a slack message from my app @@ -142,7 +139,6 @@ Important! The `vercel connect create` and `vercel connect token` commands may o | `github` | user, app | GitHub API access | | MCP servers | user, app | Any MCP server (`mcp./`) | | `snowflake` | user | Snowflake data access | -| `salesforce` | user | Salesforce API 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./` (for example `mcp.linear.app/myagent`).