Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks through the smallest useful Hosted SDK flow:
  1. Install @corsair-dev/app
  2. Create a Corsair API client
  3. Provision an instance
  4. Enable a plugin
  5. Create a tenant
  6. Issue an MCP API key
1

​
Install the SDK

npm install @corsair-dev/app
2

​
Create the client

Set your Corsair Hosted developer API key on the server.
CORSAIR_API_KEY=ch_...
Then create the client:
import { createClient } from "@corsair-dev/app";

const corsair = createClient({
  apiKey: process.env.CORSAIR_API_KEY!,
});
Target a local or self-hosted server with baseUrl: createClient({ apiKey, baseUrl: "http://localhost:3000" }).
3

​
Create an instance

An instance is a provisioned Corsair environment. It has its own runtime, installed plugins, permission policies, tenants, and MCP URL.
const instance = await corsair.instances.create({
  name: "acme-prod",
});

const inst = corsair.instance(instance.id);

console.log(instance.mcpHttpUrl);
console.log(instance.oauthCallbackUrl);
Use instance.id for future SDK calls. The name is only a display label and cannot be used as the instance path parameter.
4

​
Install a plugin

Enable a plugin on the instance. The first argument is type checked against Corsair’s generated plugin catalog.
await inst.plugins.upsert("slack", {
  mode: "cautious",
});

await inst.plugins.upsert("github", {
  authType: "oauth_2",
  useManaged: true,
});
mode controls default permission behavior:
ModeBehavior
openAllow all operations by default
cautiousAllow safe reads; require approval for risky writes
strictRead-first posture; writes require approval
readonlyAllow reads and block writes
5

​
Create a tenant

A tenant is your user, team, organization, or customer. You can pass your own ID so Corsair lines up with your database.
const tenant = await inst.tenants.create("user_123");
const t = inst.tenant(tenant.id);
You can also let Corsair generate the tenant ID:
const tenant = await inst.tenants.create();
6

​
Connect credentials

For API-key plugins, set the tenant’s account credential directly:
await t.plugins.credentials.set("slack", "api_key", "xoxb-...");
For OAuth plugins, generate an authorize URL and redirect the user:
const { authorizeUrl } = await t.plugins.oauth.authorizeUrl(
  "github",
  "https://app.example.com/integrations/github/connected",
);

// Redirect the user to authorizeUrl.
After OAuth completes, Corsair stores the tenant’s access token and redirects the browser back to returnTo.
7

​
Create an MCP key

Issue an MCP API key for the tenant. The secret is returned once.
const key = await t.mcpKeys.create("production");

console.log(key.mcpHttpUrl); // MCP endpoint
console.log(key.secret);     // Bearer token, shown once
Give key.mcpHttpUrl and key.secret to your MCP-compatible agent or AI framework.

​
Complete example

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

const corsair = createClient({
  apiKey: process.env.CORSAIR_API_KEY!,
});

const instance = await corsair.instances.create({ name: "acme-prod" });
const inst = corsair.instance(instance.id);

await inst.plugins.upsert("slack", { mode: "cautious" });

const tenant = await inst.tenants.create("user_123");
const t = inst.tenant(tenant.id);

await t.plugins.credentials.set("slack", "api_key", process.env.SLACK_BOT_TOKEN!);

const key = await t.mcpKeys.create("production");

console.log({
  mcpHttpUrl: key.mcpHttpUrl,
  secret: key.secret,
});

​
Reusing existing resources

Most production apps create an instance once, store the instance ID, then reuse it for every request. 
const inst = corsair.instance(process.env.CORSAIR_INSTANCE_ID!);
const tenant = inst.tenant(currentUser.id);
const connection = await tenant.mcpKeys.connection();
Keep the developer API key and instance ID in server-side configuration. Store tenant MCP secrets in your own secret store if you need to show them again later.

​
Next steps

Configure plugins

Install more plugins, tune permissions, and manage shared credentials.

Use MCP or direct execution

Connect an agent to MCP or run operations directly from your backend.