@corsair-dev/app

Typed SDK for the Corsair provisioning API. Manage instances, plugins, tenants, credentials, and MCP keys with full TypeScript autocomplete — including plugin IDs, auth types, and credential field names derived directly from the plugin catalog.

Installation

npm install @corsair-dev/app

Quick start

import { createClient } from "@corsair-dev/app";

const corsair = createClient({ apiKey: "ch_..." });
// Pass baseUrl to target a self-hosted server:
// createClient({ apiKey: "ch_...", baseUrl: "http://localhost:3000" })

Provisioning flow

// Create an instance (provisions its own database)
const { id } = await corsair.instances.create({ name: "my-app" });
const inst = corsair.instance(id);

// Install a plugin — authType autocompletes to what that plugin supports
await inst.plugins.upsert("slack", { mode: "cautious" });
await inst.plugins.upsert("github", { authType: "oauth_2" });

// Set OAuth app credentials (root = shared across all tenants)
await inst.plugins.credentials.setRoot("github", "client_id", "gh_app_...");
await inst.plugins.credentials.setRoot("github", "client_secret", "...");

// Set a permission override on a specific endpoint
await inst.plugins.permissions.setMode("slack", "strict");
await inst.plugins.permissions.setOverride("slack", "api.channels.archive", "deny");

Tenant flow

// Create a tenant — pass your own ID or let Corsair generate one
const tenant = await inst.tenants.create("user-abc123");
const t = inst.tenant(tenant.id);

// Set per-tenant credentials — field names autocomplete per plugin
await t.plugins.credentials.set("slack", "api_key", "xoxb-...");

// Or kick off an OAuth flow and redirect the user
const { authorizeUrl } = await t.plugins.oauth.authorizeUrl("github", "https://myapp.com/done");
// → redirect user to authorizeUrl; access_token is stored on callback

// Or send a connect page link so the user can sign into every installed plugin
const link = await t.connectLink.create();
// link.url → share with the user after provisioning

// Create an MCP API key for the tenant
const key = await t.mcpKeys.create("production");
// key.mcpHttpUrl  ← point your MCP client at this URL
// key.secret      ← bearer token (ch_...), shown exactly once — store it securely

Hosted MCP adapters

The app package also exports helpers for handing the hosted MCP URL to common agent SDKs. Use the mcpHttpUrl plus the one-time secret from t.mcpKeys.create(), or pass your own headers if your MCP endpoint uses OAuth.

import {
	claudeMcpServerConfig,
	createOpenAiMcpServer,
	createVercelAiMcpClient,
	getOpenAiMcpConfig,
} from "@corsair-dev/app";

const corsairMcp = {
	url: key.mcpHttpUrl,
	apiKey: key.secret,
};

Claude Agents SDK:

import { query } from "@anthropic-ai/claude-agent-sdk";

const stream = query({
	prompt: "Star the corsairdev/corsair repo on GitHub",
	options: {
		mcpServers: {
			corsair: claudeMcpServerConfig(corsairMcp),
		},
	},
});

OpenAI Responses API:

const tool = getOpenAiMcpConfig(corsairMcp);
// Pass `tool` in the OpenAI request's tools array.

OpenAI Agents SDK:

const corsairServer = await createOpenAiMcpServer(corsairMcp);
// Pass `corsairServer` in an Agent's mcpServers array.

Vercel AI SDK:

const corsairClient = await createVercelAiMcpClient(corsairMcp);
const tools = await corsairClient.tools();

Regenerating types

All types live in src/generated.ts, produced by scripts/gen-types.mjs from plugins/plugins.json. After adding or modifying a plugin, regenerate from the repo root:

node scripts/gen-types.mjs

Or trigger it via the package build (runs automatically as prebuild):

pnpm --filter @corsair-dev/app build
# shorthand alias inside packages/app:
pnpm gen

What gets regenerated:

• PluginId — union of every plugin ID
• PluginAuthTypes<T> — auth types that plugin supports
• PluginIntegrationFields<T> — root credential field names per plugin
• PluginAccountFields<T> — per-tenant credential field names per plugin
• PLUGINS / PLUGINS_BY_ID — static catalog arrays
• packages/app/README.md — this file

API reference

Top-level client

corsair.instances.list()
corsair.instances.create({ name })
corsair.catalog.plugins.list()

Instance scope — corsair.instance(instanceId)

inst.get()
inst.update({ name?, status? })
inst.delete()

inst.plugins.list()
inst.plugins.upsert(pluginId, { mode?, authType?, useManaged?, overrides? })
inst.plugins.delete(pluginId)

inst.plugins.permissions.get(pluginId)
inst.plugins.permissions.setMode(pluginId, mode)
inst.plugins.permissions.setOverride(pluginId, path, policy)
inst.plugins.permissions.deleteOverride(pluginId, path)

inst.plugins.credentials.list(pluginId, tenantId?)
inst.plugins.credentials.setRoot(pluginId, field, value)   // root = shared across tenants
inst.plugins.credentials.clearRoot(pluginId, field)

inst.tenants.list()
inst.tenants.create(tenantId?)

inst.runtime.refresh()
inst.runtime.status()

Tenant scope — inst.tenant(tenantId)

t.get()
t.delete()

t.plugins.credentials.set(pluginId, field, value)   // per-tenant account credential
t.plugins.credentials.clear(pluginId, field)
t.plugins.oauth.authorizeUrl(pluginId, returnTo?)   // → { authorizeUrl, state }

t.connectLink.create({ plugins?, ttlMs? })          // → { url, token, expiresAt, ttlMs }

t.mcpKeys.connection()                              // → { mcpHttpUrl, oauthDiscoveryUrl, ... }
t.mcpKeys.list()
t.mcpKeys.create(name)                              // → { secret, mcpHttpUrl, ... }
t.mcpKeys.revoke(keyId)

Error handling

All methods throw CorsairApiError on non-2xx responses:

import { CorsairApiError } from "@corsair-dev/app";

try {
  await inst.plugins.upsert("slack", { mode: "cautious" });
} catch (err) {
  if (err instanceof CorsairApiError) {
    console.error(err.status);   // HTTP status code
    console.error(err.code);     // machine-readable error code
    console.error(err.message);  // human-readable message
    console.error(err.details);  // zod field errors, if any
  }
}

Runtime validation (optional)

Every type is backed by a Zod schema exported from the package. Use them to validate webhook payloads or any external data:

import { InstanceDetailSchema } from "@corsair-dev/app";

const instance = InstanceDetailSchema.parse(rawPayload);

Plugin reference

Generated from plugins/plugins.json on 2026-05-28 — 58 plugins, catalog v1.

Plugin IDs are the string literals passed to inst.plugins.upsert() and credential methods. Root fields are set once per instance (OAuth app credentials). Account fields are set per tenant (API keys, access tokens).

| ID | Name | Auth types | Root fields | Account fields | |----|------|-----------|-------------|----------------| | airtable | Airtable | api_key | — | api_key, webhook_signature | | amplitude | Amplitude | api_key | — | api_key, webhook_signature | | asana | Asana | api_key, oauth_2 | client_id, client_secret, redirect_url | api_key, webhook_signature, one, access_token, refresh_token, expires_at, scope | | bitwarden | Bitwarden | oauth_2 | client_id, client_secret, redirect_url | access_token, refresh_token, expires_at, scope, webhook_signature | | box | Box | oauth_2 | client_id, client_secret, redirect_url | access_token, refresh_token, expires_at, scope, webhook_signature | | cal | Cal | api_key | — | api_key, webhook_signature | | calendly | Calendly | api_key | — | api_key, webhook_signature | | cloudflare | Cloudflare | api_key | — | api_key, webhook_signature | | cursor | Cursor | api_key | — | api_key, webhook_signature | | discord | Discord | api_key | — | api_key, webhook_signature | | dodopayments | DodoPayments | api_key | — | api_key, webhook_signature | | dropbox | Dropbox | oauth_2 | client_id, client_secret, redirect_url | access_token, refresh_token, expires_at, scope, webhook_signature | | exa | Exa | api_key | — | api_key, webhook_signature | | figma | Figma | api_key | — | api_key, webhook_signature | | firecrawl | Firecrawl | api_key | — | api_key, webhook_signature | | fireflies | Fireflies | api_key | — | api_key, webhook_signature | | github | Github | api_key, oauth_2 | client_id, client_secret, redirect_url | api_key, webhook_signature, access_token, refresh_token, expires_at, scope | | gitlab | Gitlab | api_key, oauth_2 | client_id, client_secret, redirect_url | api_key, webhook_signature, access_token, refresh_token, expires_at, scope | | gmail | Gmail | oauth_2 | client_id, client_secret, redirect_url, topic_id | access_token, refresh_token, expires_at, scope, webhook_signature | | googlecalendar | Google calendar | oauth_2 | client_id, client_secret, redirect_url | access_token, refresh_token, expires_at, scope, webhook_signature | | googledrive | Google drive | oauth_2 | client_id, client_secret, redirect_url | access_token, refresh_token, expires_at, scope, webhook_signature | | googlesheets | Google sheets | oauth_2 | client_id, client_secret, redirect_url | access_token, refresh_token, expires_at, scope, webhook_signature | | grafana | Grafana | api_key | — | api_key, webhook_signature, grafana_url | | hackernews | Hacker news | api_key | — | api_key, webhook_signature | | hubspot | Hubspot | api_key, oauth_2 | client_id, client_secret, redirect_url | api_key, webhook_signature, access_token, refresh_token, expires_at, scope | | intercom | Intercom | api_key | — | api_key, webhook_signature | | jira | Jira | api_key | — | api_key, webhook_signature, cloud_url | | linear | Linear | api_key, oauth_2 | client_id, client_secret, redirect_url | api_key, webhook_signature, access_token, refresh_token, expires_at, scope | | monday | Monday | api_key | — | api_key, webhook_signature | | notion | Notion | api_key, oauth_2 | client_id, client_secret, redirect_url | api_key, webhook_signature, one, access_token, refresh_token, expires_at, scope | | onedrive | Onedrive | oauth_2 | client_id, client_secret, redirect_url | access_token, refresh_token, expires_at, scope, webhook_signature, one | | openweathermap | Openweathermap | api_key | — | api_key, webhook_signature | | oura | Oura | api_key | — | api_key, webhook_signature | | outlook | Outlook | oauth_2 | client_id, client_secret, redirect_url | access_token, refresh_token, expires_at, scope, webhook_signature, one | | pagerduty | Pagerduty | api_key | — | api_key, webhook_signature | | posthog | Posthog | api_key | — | api_key, webhook_signature | | razorpay | Razorpay | api_key | — | api_key, webhook_signature | | reddit | Reddit | api_key | — | api_key, webhook_signature | | resend | Resend | api_key | — | api_key, webhook_signature | | sentry | Sentry | api_key | — | api_key, webhook_signature | | sharepoint | Sharepoint | oauth_2 | client_id, client_secret, redirect_url | access_token, refresh_token, expires_at, scope, webhook_signature, site_id | | slack | Slack | api_key, oauth_2 | client_id, client_secret, redirect_url | api_key, webhook_signature, access_token, refresh_token, expires_at, scope | | spotify | Spotify | api_key, oauth_2 | client_id, client_secret, redirect_url | api_key, webhook_signature, access_token, refresh_token, expires_at, scope | | strava | Strava | oauth_2 | client_id, client_secret, redirect_url | access_token, refresh_token, expires_at, scope, webhook_signature | | stripe | Stripe | api_key, oauth_2 | client_id, client_secret, redirect_url | api_key, webhook_signature, access_token, refresh_token, expires_at, scope | | tally | Tally | api_key | — | api_key, webhook_signature | | tavily | Tavily | api_key | — | api_key, webhook_signature | | teams | Microsoft Teams | oauth_2 | client_id, client_secret, redirect_url | access_token, refresh_token, expires_at, scope, webhook_signature, one | | telegram | Telegram | api_key, oauth_2 | client_id, client_secret, redirect_url | api_key, webhook_signature, access_token, refresh_token, expires_at, scope | | todoist | Todoist | api_key | — | api_key, webhook_signature | | trello | Trello | api_key | — | api_key, webhook_signature | | twitter | Twitter | oauth_2 | client_id, client_secret, redirect_url | access_token, refresh_token, expires_at, scope, webhook_signature | | twitterapiio | TwitterAPI.io | api_key | — | api_key, webhook_signature | | typeform | Typeform | oauth_2 | client_id, client_secret, redirect_url | access_token, refresh_token, expires_at, scope, webhook_signature | | vapi | Vapi | api_key | — | api_key, webhook_signature | | xquik | Search tweets, inspect users, manage Xquik webhooks, upload media, and run X actions from Corsair | api_key | — | api_key, webhook_signature, one | | youtube | Youtube | oauth_2 | client_id, client_secret, redirect_url | access_token, refresh_token, expires_at, scope, webhook_signature | | zoom | Zoom | oauth_2 | client_id, client_secret, redirect_url | access_token, refresh_token, expires_at, scope, webhook_signature |