How corsairdev/corsair works
1. This is a TypeScript monorepo for an integration platform, not a single app.
The main product is Corsair: a shared “integration layer” that sits between agents and third-party SaaS APIs. The repo also contains the marketing site, docs, CLI, local studio, demos, and many provider-specific packages.
2. The core runtime lives in packages/corsair.
This package is the platform boundary: auth, encryption, permissions, tenant resolution, connect flows, webhooks, hub/approval handling, and database access. It also exposes client entry points and adapters for management APIs. If you draw one central box, this is it.
3. **Provider support is implemented as one package per integration under packages/*.**
Examples include Slack, GitHub, Gmail, HubSpot, Linear, Stripe, etc. Most follow the same shape: client.ts, endpoints/, webhooks/, schema/, plus tests. These packages are leaf adapters that translate Corsair’s internal flow into each vendor’s API and event model.
4. Each integration package separates read/write API calls from webhook ingestion.
The endpoints/ layer defines typed API operations; webhooks/ defines event handlers, tenant matching, and provider-specific verification or challenge logic; schema/ defines persistence for credentials, subscriptions, and plugin state. This is the main boundary between outbound API calls and inbound event processing.
5. Permissions and approval are a central data flow.
Agent tool calls are evaluated against per-integration mode rules like open, cautious, strict, and readonly. If an action needs approval, Corsair writes a permission request to its database and returns a review link. The agent never gets direct access to credentials; the platform resolves secrets internally at call time.
6. Multi-tenancy is first-class.
The core package and many plugin packages include tenant-matcher logic, tenant-specific credential storage, and tenant-scoped webhook handling. Requests can be bound to a tenant so credentials, permissions, and stored data do not cross-contaminate across organizations.
7. Webhooks converge on shared handling infrastructure.
Each provider package exposes typed webhook handlers, but they all plug into Corsair’s shared webhook processing path. The core package includes webhook binding, signature/tenant resolution, and replay/duplication guards. The README’s “single endpoint” model is reflected throughout the repo.
8. Agent-facing consumption happens through MCP and SDK layers.
packages/mcp provides MCP server adapters for Anthropic/Claude, OpenAI, Mastra, Vercel AI, Ollama, etc. packages/ui contains reusable tool/permission UI snippets. The demo/mcp and demo/minimal apps show how agents connect to Corsair, call tools, and trigger approvals.
9. Operational tooling is split into CLI, studio, and demos.
packages/cli handles setup, auth, subscribing integrations, credential provisioning, and renewal flows. packages/studio is a local operator UI with its own server/router and React front end for inspecting plugins, permissions, tenants, chats, and scripts. demo/testing is a full Next.js test harness with TRPC, Inngest, webhook routes, and database migrations.
10. The public website and docs are separate products with their own backend concerns.
www is the marketing/OSS site built on Next.js, with auth, TRPC, webhooks, revalidation, Sanity-backed blog content, and its own database schema for OSS/integration tracking. docs is MDX documentation for the platform and plugins, and many plugin docs are generated from package metadata.
11. Data stores are used for platform state, not for vendor content itself.
The core package uses a Kysely-backed database layer for credentials, permissions, tenant links, and hub state; app-level projects like www and demo/testing use Drizzle for their own tables. The important architectural point is that persistent state is centralized in Corsair’s DB layer, while provider APIs remain external systems.
12. Build and generation are monorepo-wide concerns.
The repo uses pnpm workspaces, Turbo, tsup, Jest, and Biome/Prettier-style tooling. Scripts generate plugin docs, scaffold integrations, validate packages, and publish changed artifacts. That means most architecture is code-generated or convention-driven across the provider packages, rather than hand-wired one by one.
13. A useful diagram should show four edge layers around the core.
Put external SaaS APIs/webhooks on one side, agent runtimes/MCP clients on another, the Corsair core/control plane in the center, and operational surfaces (CLI, Studio, website/docs, demos) around it. The key flows are: agent tool call → permission/auth resolution → provider API call, and provider webhook → shared webhook handler → tenant-scoped state update.
Main entry points: corsair Corsair · webhooks Webhooks · packages Integrations · hub Hub
Components 23
Corsair core
Shared runtime boundary for auth, permissions, tenants, webhooks, hub flows, and database access.
- Corsair · Primary integration layer: auth, encryption, permissions, tenant resolution, connect, webhooks, hub state, and DB access.
packages/corsair - Auth · Key management, encryption, token exchange, plugin auth state, and auth error handling.
packages/corsair/core/auth - Permissions · Mode rules, approval messaging, and permission request handling for agent actions.
packages/corsair/core/permissions - Tenants · Tenant provisioning, account lookup, tenant links, and webhook tenant matching utilities.
packages/corsair/core/webhooks - Management API · Management handlers and framework adapters for binding Corsair into apps like Next, Express, and Hono.
packages/corsair/core/management - Hub · Connect flows, signed delivery, replay protection, credentials delivery, and browser handoff paths.
packages/corsair/hub - Database · Central platform state for credentials, permissions, tenant links, and hub records.
packages/corsair/db - Setup · Bootstrap, backfill, and platform setup routines that prepare integrations and state.
packages/corsair/setup - Client SDK · Core and React client entrypoints for agent-side and app-side consumption.
packages/corsair/client
Provider packages
Leaf integration packages that adapt Corsair flows to vendor APIs and webhook models.
- Integrations · Convention-based packages for SaaS vendors, each mapping API endpoints and webhook events into Corsair.
packages - Endpoints · Typed read/write operations that call vendor APIs from integration packages.
packages/ahrefs/endpoints - Webhooks · Provider-specific webhook handlers, verification, tenant matching, and challenge logic.
packages/airtable/webhooks - Schemas · Package-local persistence for credentials, subscriptions, and plugin-specific state.
packages/airtable/schema
Agent surface
Agent-facing runtimes, SDKs, and UI helpers used to call tools and handle approvals.
- MCP adapters · Adapters that expose Corsair tools over MCP for Claude, OpenAI, Mastra, Vercel AI, Ollama, and related runtimes.
packages/mcp/src/adapters - UI helpers · Reusable permission and plugin UI snippets used by agent-facing surfaces.
packages/ui/src
Operational surfaces
CLI, studio, demos, docs, and website products that exercise or present the platform.
- CLI · Setup, auth, subscription, credential provisioning, and renewal commands for operators.
packages/cli/src - Studio · Local server and React interface for inspecting plugins, tenants, permissions, chats, scripts, and database state.
packages/studio/src - Testing demo · Next.js harness that wires Corsair, TRPC, Inngest, webhook routes, and migrations for integration testing.
demo/testing/src - MCP demo · Minimal examples showing agent tool calls, approvals, and webhook-driven flows through Corsair.
demo/mcp - Docs · Platform documentation, plugin docs, and generated guides for management, MCP, multi-tenancy, and webhooks.
docs - Website · Marketing and OSS site with auth, TRPC, webhooks, revalidation, Sanity content, and its own database.
www
External systems
Third-party SaaS APIs, webhook sources, and platform services outside the repo.
- SaaS APIs · Third-party APIs such as Slack, GitHub, Gmail, HubSpot, Linear, Stripe, and others.
- Webhook sources · External webhook senders that trigger provider-specific handlers and Corsair’s shared processing path.
Connections 23
- MCP adapters → Client SDK: uses · MCP adapters consume Corsair client/tool definitions.
- UI helpers → Permissions: renders · UI snippets present permission and approval flows.
- CLI → Corsair: operates · CLI configures and drives core platform setup and subscriptions.
- Studio → Corsair: inspects · Studio reads and manages platform state and operations.
- Testing demo → Corsair: integration path · Demo app exercises Corsair through server routes and harness flows.
- MCP demo → MCP adapters: demonstrates · Demo shows MCP client/runtime integration paths.
- Docs → Corsair: documents · Docs explain core concepts, management, webhooks, and multi-tenancy.
- Website → Corsair: describes · Website content and OSS surfaces are built around the Corsair platform.
- Integrations → Endpoints: contains · Integration packages expose typed vendor API operations.
- Integrations → Webhooks: contains · Integration packages expose vendor-specific webhook handlers.
- Integrations → Schemas: contains · Integration packages maintain local persistence schemas.
- Endpoints → SaaS APIs: calls · Outbound requests go to third-party SaaS APIs.
- Webhook sources → Webhooks: delivers · Webhook payloads enter the provider-specific handler layer.
- Webhooks → Tenants: resolves tenant · Webhook handlers match incoming events to the correct tenant.
- Webhooks → Corsair: routes through · Provider handlers plug into Corsair’s shared webhook processing path.
- Corsair → Auth: delegates · Core runtime resolves secrets and auth at call time.
- Corsair → Permissions: evaluates · Core checks tool calls against approval and mode rules.
- Corsair → Tenants: scopes · Core binds requests, state, and webhooks to a tenant.
- Corsair → Management API: exposes · Core provides management endpoints and framework adapters.
- Corsair → Hub: drives · Core uses hub flows for connect, delivery, and replay protection.
- Corsair → Database: persists to · Core stores credentials, permissions, tenant links, and hub state.
- Setup → Database: initializes · Setup routines provision and backfill platform state.
- Hub → Webhook sources: binds · Hub-side webhook and delivery binding accepts external callbacks.