@corsair-dev/app · Doc index: llms.txt · Integrations: catalog
Prerequisites
The user adds a developer API key to.env as CORSAIR_DEV_KEY (create one). Scope it to the relevant instance(s). Secrets are shown once — never log or commit them.
id (opaque), not display name, in API calls and env (CORSAIR_INSTANCE_ID).
Goal
Use the SDK to provision and wire Corsair into the user’s project. Ask the user when something is ambiguous — do not guess instance names, tenant ids, or plugins from the repo folder name. Prefer minimum project changes: env vars, a thin server helper if needed, and only the client config (MCP, etc.) the user asked for. Do not add committed setup scripts unless the user wants repeatable/CI provisioning. The user connects OAuth / API keys via a connect link you mint in code (t.connectLink.create()), or in the dashboard for debugging.
Flow overview
Work through these in order. Ask the user at any step when you cannot infer the answer from their message or discovery results.- Product intent — how will this project use Corsair?
- Instance — find or create
- Plugins — install what the project needs
- Tenant — find or create
- Wire the project — env, code, connect link, optional MCP/SDK config
1. Product intent
Before writing project code, understand what this product does with Corsair. If unclear, ask — e.g. “What should this project do with Corsair — integrate a coding agent via MCP, add in-app chat, or call specific integrations from your backend/UI?”| Intent | What to set up |
|---|---|
| UI feeds, lists, dashboards (read-heavy) | tenant.run() with *.db.* paths — read Corsair’s synced cache; use *.api.* only on explicit refresh/write |
| Backend buttons, workflows, known API calls (writes or one-offs) | tenant.run() with *.api.* paths — no agent loop |
| Cursor, Claude Code, Codex, etc. | Coding agent MCP + client config |
| In-app AI chat (Vercel AI, OpenAI, Claude SDK) | Agent SDKs — wire MCP tools; do not put Corsair operation names in the system prompt |
2. Instance
| Situation | Action |
|---|---|
| No instances | Create one: await corsair.instances.create({ name: "…" }) — use a sensible name from the project or ask the user |
| One instance | Use it unless the user said otherwise |
| Multiple instances | Ask the user which to use — show name and id from the list |
| User named an instance | Match by display name, then use its id |
CORSAIR_INSTANCE_ID already in env | Verify it exists; confirm with the user if discovery shows others |
3. Plugins
| Situation | Action |
|---|---|
| User named integrations (e.g. GitHub, Slack) | await inst.plugins.upsert("github", { mode: "cautious" }) — see catalog for plugin ids |
| Unclear which plugins | Ask the user which services this project needs |
| Already installed | Skip unless the user wants config changes |
useManaged: true for managed OAuth when appropriate. Fetch Instances and plugins for auth types and permissions.
4. Tenant
| Situation | Action |
|---|---|
| No tenants | Create one: await inst.tenants.create("your-id") or await inst.tenants.create() for a generated id — ask the user for a tenant id if this maps to their users/workspaces |
| One tenant | Ask the user to confirm, unless they already specified it |
| Multiple tenants | Ask the user which to use — show tenant ids from the list |
CORSAIR_TENANT_ID already in env | Verify it exists on the instance |
5. Wire the project
npm install @corsair-dev/appif not already present- Persist env (never commit secrets):
CORSAIR_DEV_KEY,CORSAIR_INSTANCE_ID,CORSAIR_TENANT_ID - Add a thin server helper if the app will call Corsair — e.g.
src/lib/corsair.ts:
- Connect accounts — if the tenant still needs OAuth or API keys:
Pick operations from the catalog
Fetch the integrations catalog — same data as MCPlist_operations / get_schema, as markdown:
https://api.corsair.dev/md/integrations— plugin idshttps://api.corsair.dev/md/integrations/github— all paths for a plugin (*.api.*,*.db.*, webhooks)https://api.corsair.dev/md/integrations/github.api.issues.list— input/output schema for one path
tenant.run(). No separate probe step — read the catalog, then call the endpoint.
Direct execution (backend / UI)
See Direct execution. Read-heavy UI (feeds, search, detail pages): prefergithub.db.* (or <plugin>.db.*) so the app reads Corsair’s synced database instead of calling the third-party API on every page load. Add a user-triggered Resync (or similar) that calls *.api.* list endpoints to refresh the cache, then re-read from *.db.*.
Writes and one-off actions: use *.api.* via tenant.run() when the backend already knows the exact operation.
Coding agent MCP (only when requested)
See Coding agents and the client page (e.g. Cursor).Agent SDK (only when requested)
See Agent SDKs. Prefertenant.mcp.createVercelClient() when the server holds CORSAIR_DEV_KEY.
Wire the MCP client and pass await mcpClient.tools() to your harness. Do not add Corsair operation names, run_script usage, or plugin paths to the system prompt — the hosted MCP server exposes list_operations, get_schema, and run_script so the agent discovers and invokes operations itself. Keep the system prompt to product context only (e.g. which repo or tenant the app serves).
Reference
| Topic | Doc |
|---|---|
| Integrations catalog (paths + schemas) | api.corsair.dev/md/integrations |
| Instances, plugins, permissions | Instances and plugins |
| Tenants, connect links, OAuth | Tenants and auth |
| Types and errors | Types and errors |
| Installation (API overview) | Installation |
Safety rules
- Never log or expose tenant API key secrets, OAuth tokens, or plugin credentials
- Permission requests must be approved in Corsair; agents cannot bypass them
- Ask the user when instance, tenant, or plugin choice is ambiguous — do not hardcode or guess from repo metadata
- Avoid extra setup scripts, env keys, and MCP config the user did not ask for