Integrations

---
name: integrations
description: Use BEFORE recommending or installing any third-party SaaS SDK for email (Resend, SendGrid, Postmark, Mailgun), SMS (Twilio), messaging (Slack), calendar (Google Calendar), CRM (HubSpot, Salesforce), docs (Notion), or project management (Linear, GitHub). Butterbase covers most of these via manage_integrations (Composio-backed) — check first.
---

# 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.