TypeScript SDK Reference

@vercel/connect is the TypeScript SDK for calling Edgenivo Connect from your app. It authenticates with your Edgenivo deployment's OIDC token and exchanges it for provider tokens through the Edgenivo API. SDK methods that make API requests are subject to rate limits.

For Python, see the Python SDK Reference.

pnpm add @vercel/connect

The SDK has one runtime dependency, @vercel/oidc, which reads VERCEL_OIDC_TOKEN from the environment.

In a Edgenivo deployment, the SDK reads VERCEL_OIDC_TOKEN automatically. For local development, run vercel link followed by vercel env pull to download a development token into .env.local. The token is short-lived; re-run vercel env pull if you see authentication errors.

To override the token explicitly, pass options.vercelToken:

import { getToken } from '@vercel/connect';
 
const token = await getToken(
  'slack/acme-slack',
  { subject: { type: 'app' } },
  { vercelToken: process.env.MY_VERCEL_TOKEN },
);

See Authentication for the full caller-to-Edgenivo-Connect story.

Returns the access token string. Use when you just need the token to put in an Authorization header.

function getToken(
  connector: string,
  params: ConnectTokenParams,
  options?: ConnectOptions,
): Promise<string>;

Minimal example:

import { getToken } from '@vercel/connect';
 
const token = await getToken('slack/acme-slack', {
  subject: { type: 'app' },
  scopes: ['chat:write'],
});
 
await fetch('https://slack.com/api/chat.postMessage', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ channel: 'C123', text: 'hello' }),
});

This omits installationId and falls back to the connector's default installation, which is the predominant case (a private app installed in a single workspace). Pass installationId explicitly only for multi-tenant connectors where you need to address a specific installation. See Installations.

Returns the full response: the token, its expiry, the connector identity, and provider metadata. Use when your app needs more than the raw string, for example to display the connected workspace name or to decide whether to surface a re-authorize button.

function getTokenResponse(
  connector: string,
  params: ConnectTokenParams,
  options?: ConnectOptions,
): Promise<ConnectTokenResponse>;

Minimal example:

import { getTokenResponse } from '@vercel/connect';
 
const response = await getTokenResponse('slack/acme-slack', {
  subject: { type: 'app' },
});
 
console.log(response.connector.uid);
console.log(response.tenantId);
console.log(new Date(response.expiresAt).toISOString());

Returns the connector's stable public metadata and provider-specific configuration. Use it when your app needs connector setup values in addition to a runtime token, such as a Snowflake account identifier.

function getConnectorMetadata(
  connector: string,
  options?: ConnectOptions,
): Promise<ConnectorMetadata>;

import { getConnectorMetadata } from '@vercel/connect';
 
const connector = await getConnectorMetadata('snowflake/analytics');
const accountIdentifier = connector.vendor.accountIdentifier as string;
 
console.log(connector.name);
console.log(accountIdentifier);

The calling project and environment must be linked to the connector, just as they must be for getToken.

Use @vercel/connect@2.5.2 or later for the experimental MCP event APIs below. The MCP server must support the webhook events extension. See MCP Events for a complete subscription and receiver example, including deployment requirements.

Import the direct APIs and delivery verifier from @vercel/connect/mcp. Import the AI SDK adapter from @vercel/connect/ai-sdk.

Direct API methods take (connector, params, options?). connector is the connector identifier, such as oauth/documents. Build account scope from trusted application state, not model output or an unverified request body.

All direct methods accept Experimental_McpEventOptions as their optional third argument:

Non-success API responses use the Connect error types.

Checks event support for an authorized connection. This does not create a subscription or retrieve event occurrences.

• Parameters: Experimental_McpEventSourceInput.
• Returns: Promise<{ status: 'supported' | 'unsupported' | 'unavailable' | 'needs_auth' }>.

unsupported means the server does not support events. unavailable means discovery could not establish support; don't treat it as confirmed lack of support. needs_auth requires account authorization before discovery can complete.

Lists event definitions from the authorized server's catalog.

• Parameters: Experimental_McpEventSourceInput plus optional cursor: string.
• Returns: Promise<{ events: Experimental_McpEventDescriptor[]; nextCursor?: string }>.

Each descriptor includes name, optional description, inputSchema, payloadSchema, and delivery modes (webhook, poll, or push). Follow nextCursor until absent. Catalog discovery does not poll for occurrences; Connect subscriptions use webhook delivery.

Creates a subscription and returns Promise<Experimental_McpSubscription>. The input type is Experimental_McpSubscribeInput:

Pass ttlMs: null for an indefinite watch. Connect manages provider lease renewal separately from this application lifetime. Omitting ttlMs, supplying an invalid duration, or passing expiresAt throws a TypeError before the SDK sends a request. Responses still include the resolved expiresAt deadline.

Creation can return pending while upstream registration finishes. Persist the returned ID and its authorized application binding.

Lists subscriptions for the connector, account, and calling project/environment. The list is not scoped to a conversation or the subscription's context.

• Parameters: Experimental_McpEventScope plus optional cursor: string, limit: number, and status: Experimental_McpSubscriptionStatus.
• Returns: Promise<{ subscriptions: Experimental_McpSubscription[]; pagination: { next: string | null } }>.

Pass pagination.next as the next request's cursor. A null value ends pagination. This differs from event catalog and AI SDK adapter pagination, which use nextCursor.

Retrieves a subscription by ID after checking access.

• Parameters: Experimental_McpSubscriptionLookupInput.
• Returns: Promise<Experimental_McpSubscription>.

Pass expectedSubject when looking up a subscription on behalf of an account. Knowing a subscription ID does not establish ownership.

Stops local delivery and attempts provider cleanup.

• Parameters: Experimental_McpSubscriptionLookupInput.
• Returns: Promise<Experimental_McpSubscription>.

Pass expectedSubject for account-bound calls. A response with status: 'stopped' and cleanupStatus: 'pending' means local delivery has stopped but provider cleanup remains unfinished. Retry unsubscribe to finish cleanup.

Requests a bulk stop for the connector, subject, and calling project/environment.

• Parameters: Experimental_McpEventScope plus required idempotencyKey: string.
• Returns: Promise<{ accepted: true }>.

This affects every subscription in that scope, not just one conversation or receiver path. accepted: true acknowledges the request; it does not mean every provider subscription has finished cleanup.

Direct subscribe, get, and unsubscribe calls return this object. Direct list calls return an array of these objects.

See subscription lifecycle for status handling and cleanup behavior.

Returns an Experimental_ConnectEventsAdapter for AI SDK's experimental_events.adapter. It is exported from @vercel/connect/ai-sdk. Use @ai-sdk/mcp@2.0.76 or later with @vercel/connect@2.5.2 or later so both packages use the ttlMs creation input.

The returned adapter implements synchronous createAdapter({ transport }). AI SDK supplies { type: 'http' | 'sse', url: string } or { type: 'custom' }. For custom transports without an explicit mcpUrl, Connect uses the connector's configured endpoint. You don't need to wrap the adapter in another factory.

The bound operations are:

The adapter uses the same subscription lifetime rules as the direct API.

All operations return promises. Experimental_ConnectEventsSubscription contains id, name, JSON arguments, status, expiresAt, and optional cleanupStatus. The adapter binds account scope and automatically supplies expectedSubject for get and unsubscribe. Its request options accept only signal, timeout, and maxTotalTimeout; they cannot override workload identity or API region.

Event catalog discovery remains an MCP request through the AI SDK client. Subscription operations use Connect. See the AI SDK subscription example.

Authenticates a forwarded Connect delivery and validates its envelope:

import type {
  Experimental_McpEventDelivery,
  Experimental_VerifyMcpEventOptions,
} from '@vercel/connect/mcp';
 
declare function experimental_verifyMcpEvent(
  request: Request,
  options: Experimental_VerifyMcpEventOptions,
): Promise<Experimental_McpEventDelivery>;

The function consumes the request body. It does not acknowledge delivery, deduplicate it, or run application work. Durably accept by deliveryId before returning success. Use this verifier for Connect-forwarded envelopes, not AI SDK's experimental_createMCPEventWebhook helper for direct provider webhooks.

Experimental_McpEventDelivery includes version: 1, deliveryId, subscriptionId, source: { type: 'mcp', connectorId }, and saved context, plus one of:

• event: eventId, name, timestamp, JSON data, nullable cursor, and optional _meta.
• control.type: 'gap': nullable cursor and optional truncated: true.
• control.type: 'terminated': error with numeric code, message, and optional data.

Verification failures throw Experimental_McpEventVerificationError:

Reject invalid deliveries. Treat configuration and verification availability failures as retryable receiver failures rather than acknowledging or processing the event. See the receiver example.

A union with four variants:

type ConnectTokenSubject =
  | { type: 'app' }
  | { type: 'user'; id: string; issuer?: string }
  | {
      type: 'jwt-bearer';
      sub: string;
      iss?: string;
      aud?: string;
      additionalClaims?: Record<string, unknown>;
    }
  | { type?: 'token'; token: string };

The SDK infers type: 'token' for subject: { token: '...' } before sending the request. Other variants require their explicit type.

Revokes the provider grant for a connector subject and clears the SDK's in-process token cache. Provider support for revocation varies; see Revocation.

import { revokeToken } from '@vercel/connect';
 
await revokeToken('oauth/linear', {
  subject: { type: 'user', id: 'user_123' },
});

Removes one cached token without revoking its provider grant. Pass the same connector and complete request parameters that you used for getToken or getTokenResponse. The next request for that cache entry fetches a fresh token.

import { deleteTokenCacheEntry, getToken } from '@vercel/connect';
 
const params = {
  subject: { type: 'app' as const },
  scopes: ['chat:write'],
};
 
let token = await getToken('slack/acme-slack', params);
 
// If Slack rejects this token with a 401:
deleteTokenCacheEntry('slack/acme-slack', params);
token = await getToken('slack/acme-slack', params);

The SDK maintains an in-process LRU cache with a maximum of 100 entries, keyed by the connector and the full request params. Cached tokens are reused on subsequent calls until they fall inside the validityBufferMs window, at which point the next call fetches a fresh one.

Pass { forceRefresh: true } in ConnectOptions to bypass the cache for a request. Use deleteTokenCacheEntry when you only need to discard one rejected token while preserving normal caching for future calls.

The SDK throws typed error classes you can match on with instanceof:

Most SDK calls have a vercel connect CLI equivalent. The CLI supports --subject, --installation-id, and --scopes. The SDK additionally supports resources and authorizationDetails, which are not exposed through the CLI. The CLI supports --triggers on vercel connect attach, which has no SDK equivalent.

• Quickstart: Create a connector and request your first token from TypeScript.
• Python SDK Reference: The same API for Python.
• Tokens: How a token request is shaped and what each field does.
• Authentication: What the OIDC token carries and how the API checks it.