documentation
06 integrations

Composio integration

Composio is a hosted MCP gateway that exposes hundreds of third-party SaaS toolkits behind one API key. Install a toolkit from the dashboard, and every action it offers becomes available to every agent that has access to it — no custom wiring, no per-service MCP servers, no local runtime.

What this page is for

If you want your agents to read Gmail, create Linear issues, update HubSpot contacts, or post to Slack, you have two options: install and configure a separate MCP server per service, or install one Composio integration and get hundreds of services behind a single key.

This page is the concept and setup guide — prerequisites, the governance decisions you should make first, how toolkits install, how they bill, and how approvals work. For the UI walkthrough of the dashboard page itself, see Dashboard → Composio.

What Composio is

Composio is a third-party SaaS that aggregates MCP-compatible toolkits for hundreds of services and exposes them via a single HTTP endpoint. Exolvra integrates with Composio at the catalog layer: the dashboard shows you every toolkit Composio offers, and installing one creates a standard Exolvra MCP installation pointed at Composio’s hosted endpoint for that toolkit.

Under the hood, a Composio toolkit is just an MCP server — it reuses the same access control, audit log, and approval plumbing as any other MCP install. The difference is that the server is hosted by Composio, not run locally, and one Composio API key unlocks the whole catalog.

Prerequisites

  1. A Composio account — sign up at composio.dev and generate an API key
  2. Admin role on the Exolvra instance — Composio install is admin-only
  3. Some clarity on governance — before opening the catalog, decide whether you want allowlist enforcement and which toolkits to block (see Settings → Security → Composio governance)

Composio doesn’t require Node or Python on the host — its toolkits run in Composio’s cloud. Any instance with HTTPS egress can use them.

Setup

1. Configure the API key

Open Settings → Providers and paste your Composio API key. It’s stored encrypted at rest alongside other provider credentials.

Alternatively, on a fresh install where no key is configured yet, the Composio page itself has a prominent “API key missing” banner that points to the settings page.

2. Review governance

Open Settings → Security and scroll to the Composio Governance card. Decide:

  • Enforce budget — when on, Composio action costs count against daily/monthly budget limits. Turn off only for on-prem BYOK deployments where Composio bills the operator directly
  • Enforce toolkit allowlist — when on, only ticked toolkits can be installed
  • Blocked toolkits — always enforced regardless of allowlist state
  • Require approval for specific actions — fully-qualified toolkit.action names that need human sign-off before running

A sensible initial setup:

  • Allowlist off (let the team explore)
  • Block toolkits that access personal communications you don’t want exposed
  • Require approval on anything that writes to external systems (send email, create contact, post message)

3. Open the catalog

Open /integrations/composio. You’ll see every toolkit Composio offers, grouped by category, with a search box and category pills. The catalog shows each toolkit’s name, description, action count, and current status (Available, Installed, or Blocked).

4. Install a toolkit

Click Install on any available toolkit. Exolvra creates an MCP installation pointing at Composio’s endpoint for that toolkit. Per-toolkit credentials — if the toolkit needs them (e.g., OAuth with the underlying service) — are handled via Composio’s hosted auth flow.

5. Grant agent access

By default, an installed toolkit is not available to any agent — it has to be explicitly granted. Click Manage access on the installed card and tick the agents that should see the toolkit’s actions.

This is the same per-agent MCP access mechanism as any other MCP install. See MCP Library for the general pattern.

How it looks to an agent

After install and access grant, the toolkit’s actions appear in the agent’s tool list as regular tool calls. An agent might call:

  • gmail.send_email — with to, subject, body arguments
  • linear.create_issue — with title, description, team_id
  • slack_api.send_message — with channel, text

From the agent’s point of view, there’s no difference between a Composio tool and a local one. The call goes through, audit logs show it alongside other tool calls, and the result streams back.

Cost

Composio bills per action call. The per-call cost varies by toolkit — the dashboard tracks it under Budget → External services alongside LLM cost.

If Enforce budget is on (the default for hosted mode), Composio action cost rolls into the daily/monthly budget — an agent that’s already spent its daily LLM budget can’t make Composio calls either. If Enforce budget is off, Composio cost is tracked for visibility but doesn’t block.

When the catalog lacks a precise per-call cost signal, Exolvra records a conservative $0.05 per call default. You can override the default from configuration.

Approvals

Actions flagged for approval — either by the catalog (requires_approval: true) or by the admin’s Require approval list — route through Admin → Review queues → Approvals before they execute. The agent pauses on the call, the request lands in the inbox, a human approves or rejects, the agent continues.

Default timeout on approval is 5 minutes — an unanswered request aborts with an error. Raise or lower the timeout from the Exolvra:Composio:ApprovalTimeoutMinutes configuration value.

Common pitfalls

Installing without configuring access. A toolkit installed but not granted to any agent is inert — no agent can see its actions. Always follow install with a Manage access step.

Skipping governance. The default is “any non-blocked toolkit installs”. For a public-facing or multi-tenant deployment, that’s too open. Set the blocklist and approval rules before opening the catalog to your team.

Forgetting the per-action approval list. Catalog defaults cover the obvious things (gmail.send_email is approval-gated by default). For actions the catalog doesn’t mark, you have to explicitly add them to the admin list — otherwise an agent can run them without any human check.

Running hosted Composio with EnforceBudget: false. If Composio bills you (not the operator), turning budget enforcement off means a runaway agent can’t be stopped by the budget system. Keep it on unless you know you’re in BYOK mode.

Where to go next