integrations

Butterbase Integrations (Composio)

The manage_integrations MCP tool gives every Butterbase app access to Composio's toolkit catalog. Before installing a third-party SDK for any of the use cases below, check whether Composio covers it.

Decision rule

User wants: send email / Slack message / create calendar event / post GitHub issue / etc.

Step 1: manage_integrations(app_id, action: "list_available", search: "<keyword>")
Step 2: If a toolkit covers it → use the Composio path (configure → list_tools → execute_action)
Step 3: If no toolkit covers it OR latency is critical → fall back to a direct API call in a function

Common toolkit map

Use case	Composio toolkit	Replaces
Send email	gmail	Resend, SendGrid, Postmark, Mailgun
Read inbox / search	gmail	Custom IMAP, Nylas
Create calendar event	google_calendar	Cal.com API, custom OAuth
Post Slack message	slack	Slack Web API
Create GitHub issue / PR	github	Octokit
Notion page / database row	notion	Notion API
Linear ticket	linear	Linear SDK
HubSpot contact / deal	hubspot	HubSpot API
Salesforce record	salesforce	Salesforce REST

Always call list_available first — the catalog grows.

Flow

1. configure:      manage_integrations(app_id, action: "configure", toolkit: "gmail", scopes: ["gmail.send"])
2. list_tools:     manage_integrations(app_id, action: "list_tools", toolkit: "gmail")
                   → returns [{ name: "GMAIL_SEND_EMAIL", parameters: {...} }, ...]
3. execute_action: manage_integrations(
                     app_id, action: "execute_action",
                     tool_name: "GMAIL_SEND_EMAIL",
                     params: { to, subject, body },
                     user_id: "<end-user uuid>"   // omit for service-level
                   )

Per-user OAuth vs. service-level

• Service-level (omit user_id): the integration runs as the app owner. Use for system notifications, internal automation.
• Per-user (set user_id): the integration runs as the specified end-user. The user must have completed Composio's OAuth flow. Use for "send on behalf of user."

When NOT to use Composio

• ❌ Latency-critical hot path (Composio adds a round-trip). Use a direct API call from a function.
• ❌ Toolkit doesn't exist yet (check list_available). Fall back to a direct API call.
• ❌ The user needs a custom auth flow that Composio doesn't support.

Documentation

For the catalog and per-toolkit scope reference, WebFetch https://docs.butterbase.ai/integrations or call butterbase_docs with topic: "integrations".

Anti-patterns

• ❌ Recommending Resend / SendGrid without checking manage_integrations list_available first.
• ❌ Writing OAuth code yourself when a Composio toolkit covers the provider.
• ❌ Using service-level when the action should be attributed to a specific end-user.