Concepts
Project
Everything lives in a project: API keys, auth configs, connected accounts, MCP servers, triggers, the webhook and the logs. Projects have members with the roles owner, admin and member.
Toolkit and tool
A toolkit is one app, such as github or slack. It has tools, each an operation with a name like GITHUB_CREATE_ISSUE, a description and a JSON schema for its input. Tools marked read-only don't change anything; tools marked destructive delete or overwrite. Browse them in the catalogue or with GET /api/v3/tools.
User
A user is whoever your agent acts for. You choose the id (user_id), usually your own database id for that person. There is nothing to create: a user exists once they have a connection.
Auth config
An auth config (ac_...) says how a toolkit is authenticated in your project:
| Scheme | What the user provides |
|---|---|
OAUTH2 | Signs in to the app. Uses our OAuth app (managed) where one exists, or yours. |
API_KEY | An API key. |
BEARER_TOKEN | An access token, such as a GitHub personal access token. |
BASIC | A username and a password or token. |
NO_AUTH | Nothing. |
An auth config can also limit which tools may run (restrict_to_following_tools) and which OAuth scopes are asked for.
Connected account
A connected account (ca_...) is one user's credentials for one auth config. Its status is one of:
| Status | Meaning |
|---|---|
INITIATED | A connect link was created and the user hasn't finished. |
ACTIVE | Ready. Tools run with it. |
EXPIRED | The token ran out and could not be refreshed. Send a new link. |
FAILED | The provider refused the sign-in or the key. |
DISABLED | Switched off by you. |
A user can have several accounts for one toolkit. Calls use the newest active one unless you pass connected_account_id.
MCP server
An MCP server (mcp_...) is a URL your agent connects to. A custom server exposes the tools of chosen toolkits. A router exposes five meta tools that search the whole catalogue. A session (trs_...) is a router bound to one user.
Trigger
A trigger type (GITHUB_ISSUE_EVENT) describes an event an app can send. A trigger instance (ti_...) switches it on for one connected account with a config, such as the repository to watch. Events go to your project webhook.