Concepts

Six nouns cover the whole product.

Project#

Your tenant. A project owns API keys, a redirect allow-list and a usage quota. Every request is scoped to the project that owns the API key, and one project can never see another's data.

End user#

Your user, identified by a user_id string that you choose, such as user_1 or telegram:12345. Setu does not store emails or passwords for end users. Connections belong to the pair (project, user_id).

Toolkit#

One app, such as github or slack. A toolkit declares how to sign in (OAuth 2 or an API key), which scopes it may ask for, which host it may call, and its list of actions. Toolkits are plain YAML files in the integrations/ folder.

Action#

One callable operation, identified as toolkit.action, for example github.create_issue. An action has:

• an input schema (JSON Schema) that Setu validates before anything is sent;
• a risk level: read, write or destructive;
• the scopes it needs;
• an optional output shape, so results stay small and predictable.

Destructive actions refuse to run unless the caller passes confirm: true.

When a model calls an action as a tool, the name is written toolkit-action (a hyphen) because many model APIs reject dots. The SDKs convert it back for you.

Connection#

A user's authorization for one toolkit. It stores the encrypted tokens and a label such as the GitHub username. Status is initiated, active, needs_reauth or revoked. Deleting a connection revokes it and erases the stored secrets.

Session#

A short-lived, scoped handle for MCP clients. It binds a user_id to a set of toolkits or actions and returns an mcp_url. The session id inside that URL is a secret: anyone holding it can act as that user, within the session's scope, until it expires.

How a call flows#

execute("github.create_issue")
  1. find the user's GitHub connection in your project
  2. check the action's risk level and the session scope
  3. validate input against the action's schema
  4. decrypt the token in memory and build the request (host is fixed by the toolkit)
  5. send it, refresh the token once on a 401, retry reads on 5xx
  6. map provider errors to a stable error code and return the extracted result