kortix-connectors
Use Kortix connectors to reach external systems from a session, an App, a Convex backend, or an external program. Use the `kortix connectors` CLI for agent work, `@kortix/sdk` for durable TypeScript w
SKILL.mdpackages/starter/templates/managed/skills/kortix-connectors/SKILL.md
GitHub<skill name="kortix-connectors">
<model>
Three things, one per question:
- Profile (a connector): ONE way to reach an app, such as Linear over MCP.
Its slug is what
kortix connectors call <slug> <action>takes. An app is installed once per way. - Account: WHO a call runs as. A sign-in on the profile, shared with the workspace or private to one member. One profile holds several.
- Rule set (a policy set): WHAT one agent may do on the profile. Named
tool rules, given to an agent in
agents.<name>.policy_sets.
Every call is decided in this order. The first layer with a matching rule decides:
- workspace
policies:(nothing overrides them); - the calling agent's rule set on this profile;
- the profile's base
policies:; sensitive: true→ approval;policy.default_mode.
The gateway holds every credential, applies these rules, runs the call, and
audits it. The sandbox carries only KORTIX_TOKEN.
</model>
Other reads: kortix connectors discover "<intent>" searches actions;
kortix connectors policy <slug> effective shows what each tool does for you
and which layer decided.
</fast-path>
Every time you call a profile you have not listed accounts for:
kortix connectors accounts <slug>lists them, default first.- One account: call.
- Several, and the human named one: pass
--account <label|id|me|project>(me= your own private default,project= the shared default). - Several, and it is unclear which one: ASK. With nothing named and nothing
pinned the call is refused (
account_required). A human pins a default withkortix connectors accounts <slug> --default <label>.
Report which account ran when it could matter: read the result's account.
$ kortix connectors accounts gmail
LABEL CONNECTED AS OWNER DEFAULT CONNECTION ID
personal@example.com personal@example.com private no 11111111-…
work@example.com work@example.com private no 22222222-…
Asked "check my gmail" here, ask which mailbox. Told "the work one", call
with --account "work@example.com" and say "Checked work@example.com — …".
Another account ("connect my other Gmail"): mint a link with a label,
kortix connectors connect <slug> --label "Personal Gmail". The human names
the account and chooses who can use it; you are told its name. Never install
a second profile to get a second account.
Email inboxes are accounts of kortix_email. Kortix fills in inbox_id:
kortix connectors accounts kortix_email
kortix connectors call kortix_email reply_message \
'{"thread_id":"<thread-id>","message_id":"<message-id>","text":"Reply text"}' \
--account "<inbox address>"
</accounts>
<approvals>
A rule may hold a call for a human. Pass `--reason "<what this does>"` on
every write whose args are only ids (`send_draft`: who it goes to, the
subject, the body; a delete: what goes). The approver sees it next to the
args.
A held call returns approval_url: share it, then stop the turn. Approve
runs the call once, as you, and your next prompt carries the result. Do not
repeat the call: a repeat while it waits returns the same execution_id. A
deny, and any message with it, also arrives as your next prompt. A deny with
a message is an instruction. kortix review show call:<execution_id> shows
the decision and detail.run (the run state and a redacted result).
Read approval_instructions every time. When the response has no
runs_on_approval (an older or unscoped token), approval alone does not run
the call: when the prompt says approved, repeat the exact same call (same
arguments and --account) within 15 minutes, and that call runs once. In a Slack or Teams session Kortix posts the
approval card in the thread (approval_instructions says so): do not repost
the link.
</approvals>
kortix connectors catalog gmail # one row per app
kortix connectors catalog crm --kind mcp,composio # kortix, mcp, composio, openapi, graphql
kortix connectors catalog notes --one-click # apps the human connects by signing in
kortix connectors catalog show composio:gmail # every way to connect it + its tools
Ways to connect, best first (the first is marked recommended):
- built by Kortix (
kind: kortix): the channels Slack, Microsoft Teams, Email, Telegram and Discord, and Computer. They are never installed. The human sets them up:kortix channels connect(Slack;--platform teams),kortix channels email inboxes add, Telegram and Discord on their web pages, Computer withnpx --yes @kortix/agent-tunnel@latest connecton that machine or the desktop app; - a one-click MCP server: the vendor's own; the human only signs in;
- Composio: a third-party partner that runs the sign-in (one click);
- an MCP server that needs the human's own OAuth app or key, then the REST (OpenAPI) and GraphQL APIs: they need a key or token after install.
kortix connectors catalog install kortix:linear
kortix connectors catalog install composio:gmail --name "Support inbox"
kortix connectors catalog install <id> --way <way-id>
Install is idempotent: the same app the same way exits 3 and names the slug
it already has. --new-profile makes a second profile; use it only for a
human who asks for one. Another way of connecting (Stripe over MCP and over
REST) is its own profile: different tools, different sign-in.
The catalog is an index, not a list of what may be connected. Prefer the
vendor's own MCP server over Composio whenever it exists. A way marked
catalogue has no URL installs with the server URL: get it from the human or
the vendor's docs, then
kortix connectors catalog install <id> --way <way-id> --url <url>.
The catalog is large, not complete. When it lacks the app, search the web for
the vendor's MCP server (its developer docs, registry.modelcontextprotocol.io)
or OpenAPI spec, then add it:
kortix connectors add acme --provider mcp --url https://mcp.acme.com/mcp --transport http --apply
kortix connectors add acme --provider openapi --spec https://acme.com/openapi.json --apply
Without --apply, add edits the kortix.yaml of the clone you are in
(kortix workspaces clone; /workspace has none at boot), landed through a change request. A
server URL that neither the catalog publishes nor the workspace already has
needs a one-time approval of that exact URL: the answer is
custom_connector_needs_human with a setup_url. Hand the human the link;
it opens the server prefilled, and adding it is the approval. Do not retry.
Credentials:
- an API key the human gave you:
kortix secrets set NAME=- --scope connector, thenkortix connectors secret <slug> NAME; - a key you lack:
kortix secrets request NAME --scope connector; - OAuth2 client credentials (an OpenAPI or HTTP API with a client id and
secret):
kortix connectors credential <slug> --oauth2-client-credentials --token-url <url> --client-id <id> --client-secret-from - [--scope "<a b>"], secret on stdin. Kortix fetches and refreshes the tokens.
Pipedream exists only for rollback compatibility with already-declared connectors. Never add one. If the catalog and the web have nothing, stop, explain the gap, and ask the human. </adding-connectors>
<policy-sets> A rule set is a named rule list on one profile (`connectors[].policy_sets`). Give an agent one with `agents.<name>.policy_sets: { <slug>: <set> }`. A caller with no set (a person's token, a script, a trigger poll) gets the base rules. A subagent in your session (`agent` tool, `session: "same"`) runs under your set; a named subagent in its own session runs under its own agent's set.connectors:
- slug: gmail
provider: composio
app: gmail
policy_sets:
read_only:
description: Read and search, never send
policies:
- match: send_*
action: block
agents:
support:
tools: "*"
connectors: [gmail]
policy_sets:
gmail: read_only
Each command commits kortix.yaml on the default branch and syncs:
kortix connectors policy-sets gmail ls # sets + the agents that use each
kortix connectors policy-sets gmail create read_only --template read-only # or ask-before-writes
kortix connectors policy gmail --policy-set read_only set "send_*" block # ls, set, rm, clear
kortix connectors policy gmail effective --policy-set read_only # what each tool does now
kortix connectors policy-sets gmail rename read_only readonly # agents move with it
kortix connectors policy-sets gmail rm readonly # refused while an agent uses it
kortix agents scope support --policy-set gmail=read_only # gmail=base removes the entry
kortix connectors agents gmail # who calls gmail, with which set
kortix connectors rules # every agent × every profile
--template read-onlyblocks every tool that is not a read;ask-before-writesasks for them. Unknown-risk tools count as writes. Check the result withpolicy <slug> effective.- A name is
[a-z0-9][a-z0-9_-]{0,63};baseis reserved. Channel profiles andcomputerhold no sets. - Changing any agent's
policy_setsneedsworkspace.agent.writeANDworkspace.connector.write. Without both in your own grant you cannot change any entry, your own included (403 agent_grant_escalation): ask the human. list_connectors(MCP) showspolicy_setper profile: the set YOUR agent runs under,nullfor base rules.</policy-sets>
import { createKortix } from '@kortix/sdk';
const kortix = createKortix({
backendUrl: process.env.KORTIX_API_URL!,
getToken: async () => process.env.KORTIX_TOKEN ?? null,
});
const connectors = process.env.KORTIX_PROJECT_ID
? kortix.project(process.env.KORTIX_PROJECT_ID).connectors
: kortix.connectors;
const result = await connectors.call(
'kortix_email.reply_message',
{ thread_id: '<thread-id>', message_id: '<message-id>', text: 'Reply text' },
{ account: '<inbox address>' },
);
if (!result.ok) throw new Error(`Call failed: ${result.reason ?? result.status ?? 'unknown'}`);
Run scripts with bun run path/to/script.ts. Keep provider credentials out
of code and repository files.
</sdk-workflows>
| Where the code runs | Credential | Reaches |
|---|---|---|
| App, browser | backendUrl: '/_kortix/api/v1' + kortixAppViewerToken() (App set to --viewer api) |
the viewer's shared and private accounts |
| App, server | createAppViewerKortix(request, { backendUrl }) |
the same, per request |
| Convex action, App job with no viewer | a service account bearer (kortix_sa_…) in an env var |
shared accounts nobody narrowed; never a private one |
| External program, CI | a personal access token, kortix tokens new <name> --workspace <id> |
the token owner's shared and private accounts |
A service account is a human step: ask the person to run
kortix tokens service-accounts new <name> and
kortix access grant --service-account <id> --role member --workspace <id>,
and to store the bearer (npx convex env set KORTIX_API_KEY … for Convex; a
workspace secret under apps.<slug>.secrets for an App, not named KORTIX_*).
Build the rest while you wait. Recipes: references/sdk.md.
</from-apps-and-backends>