Integrations
Apps, accounts, MCP servers, and triggers.
Integrations connect the outside world: third-party app accounts, MCP tool servers, and event triggers that run agents. The Apps page manages the workspace side, with MCP connectors at the top and connections grouped by app below. Each agent attaches its own apps and triggers in the editor.
Connecting an app account, attaching an app to an agent, and creating a
trigger all need the integrations plan feature (Pro and Enterprise).
Accounts
An integration is one connected account. Its provider is one of:
composio: Composio holds the credential, and only its account id is stored.mcp: tokens from an MCP server's own OAuth flow, stored encrypted.oauth: an app this deployment registered with a known provider, such as Notion for datasources.
Scope is user (the default, private to whoever connected it) or connector
(shared across the org). Only the display name can be edited. Each row also
shows where it's used: trigger, connector-app, and user-app counts.
Connecting depends on the app's auth scheme. OAuth opens a popup and polls. API-key style credentials submit a form, and only the Composio account id is kept, never the secret. Deleting an integration deletes its triggers first.
Agent apps
An agent app attaches a Composio toolkit's actions to one agent:
| Setting | Values |
|---|---|
mode | connector uses one shared account, pinned by integration id. user has each chat user act through their own account, found at chat time by app slug. |
transport | direct (the default) builds one tool per action, up to 200 per toolkit. mcp mounts Composio's hosted MCP session for the toolkit, which costs a session on every turn and falls back to direct if the session fails. |
enabledActions | Optional allowlist of action slugs. Unset means every action. |
beforeExecute / afterExecute | Hooks around every action of the toolkit, with runtime.toolName and runtime.appSlug (see Tools). |
sharing | Who may use the app's actions. Unset means the agent's audience. |
enabled | Turns the app off without removing it. |
In user mode, a chat user who hasn't connected the app yet gets a
connect_<slug> tool instead. The agent offers a Connect button, and the
turn resumes once the user authorizes. A user outside the app's sharing
audience gets neither the actions nor the Connect tool.
MCP servers
MCP servers are registered once on the Apps page, and agents reference them. A server comes from a URL, over SSE or streamable HTTP, or from Composio: pick connected Composio apps and they're served through Composio's hosted MCP session, created on each turn.
- Auth is
none,header, oroauth. Static headers are capped at 50, with valid names and no line breaks in values. - OAuth discovers everything from the server. Endpoint overrides were
removed because discovery decides. If the authorization server doesn't
support dynamic client registration, paste a pre-registered
client_id, plus an optionalclient_secret,scopes, andredirect_uri. auth_scopeisshared(the default) oruser. Withshared, an admin authorizes one account on the Apps page, and it's the only scope that works in trigger-fired runs. Withuser, each chat user authorizes their own account through a Connect card in the chat.sharinglimits who may use the server's tools. Unset means it inherits the agent's audience.
The enabled flag lives on the agent's reference, not on the server, so one
agent can switch a shared server off without affecting others.
Triggers
Triggers run an agent when an app event arrives, from Gmail, Slack, Google Calendar, or Outlook. The integration must be active when you create the trigger. Each trigger has:
| Field | Notes |
|---|---|
name | Label, up to 120 characters |
eventType | The provider's event, such as GMAIL_NEW_GMAIL_MESSAGE |
filter | Optional, provider-specific |
enabled | Defaults to on |
promptTemplate | Up to 8,000 characters. {{path.to.field}} reads the raw event payload, and missing keys render empty. Each app has a default, and {{__payloadJson}} gives the whole event. |
replyEnabled | Gives the run the app's actions plus a reply tool that answers in the original thread (Gmail, Slack, Outlook) |
replyRequireApproval | On by default when replies are on, so a person approves each reply in the thread |
A new trigger subscribes upstream first. Composio creates the subscription
before the database row, so a rejected event type leaves no half-broken row.
Editing eventType or filter re-creates the upstream subscription. Other
edits stay local.
On delivery, the webhook signature (HMAC) is checked, the trigger is found by its provider id, and a job is queued with the verbatim payload. The event id makes the job idempotent. Disabled triggers are ignored. Events from the same Gmail, Slack, or Outlook thread continue the same chat thread, and the fired thread records its app source. Gmail skips the agent's own sent mail and uses it to match later replies back to the right thread. If Composio disables a trigger upstream, it's switched off locally too, with the reason recorded.