Integrations

An integration is a connection between your workspace and an external service — Slack, GitHub, an MCP server, an OAuth provider. Integrations live at the workspace level and bring two things into reach at once: tools your agents can call, and events your agents can be triggered by.

What an integration gives you

Connect once and every agent in the workspace can:

• Use the integration as a tool. A connected MCP server registers its capabilities so agents can call them. A connected GitHub App lets agents read repositories, comment on pull requests, and open issues using workspace-scoped credentials.
• React to its events. Once an integration is connected, map specific events (a GitHub pull request, a Slack mention) to fire an agent. The Automation guide covers how triggers are wired.

Connections are workspace-scoped: each integration is granted to agents explicitly, so connecting one doesn't expose it automatically.

Use an integration as a tool in a recipe

Once an integration is connected and attached to an agent, the agent can call it directly from a recipe node by declaring the integration name in @mcp_servers:

# @node {"function": "my_agent.nodes:post_update"}
# @mcp_servers ["slack"]
PostUpdate == TRUE

Slack — the slack platform server exposes two tools: send_message(channel, text, thread_ts?, unfurl?) and list_channels(). Pass thread_ts from a prior call to reply in a thread. Link previews are off by default; unfurl=true lets Slack render preview cards for that one message. A top-level post opens a conversation: a reply in its thread reaches the agent as its next message, and the answer streams back into the same thread. The agent can post to any channel the Levain bot is invited to. If Slack isn't connected or attached, the tools return an actionable message telling the agent to ask the workspace owner to connect — the run doesn't fail.

GitHub — declare the integration's display name (e.g. "github") or the workspace display name (e.g. "acme (organization)"). The server exposes eleven tools: list_repositories, list_issues, get_issue, create_issue, comment_on_issue, update_issue, create_pull_request, list_pull_requests, create_branch, commit_file, and commit_workspace_file — the last three let a recipe author a PR end to end (create the head branch, commit file contents, then open the PR) instead of only reading and commenting. commit_file takes inline text content; commit_workspace_file commits a file already staged in the agent's sandbox workspace instead, so binary output (a generated image, a downloaded asset) never has to round-trip through the model as text. The repo argument accepts owner/name or a bare repository name.

Restrict which tools the agent sees with tool_allowlist on the integration attachment — tools not listed are dropped at build time so the model never sees them. Set this via the dashboard (Agent → Integrations → Edit) or with PATCH /api/v1/agents/{id}/integrations/{integration_id}:

{"tool_allowlist": ["create_issue", "comment_on_issue"]}

Workspace-wide access

By default an agent only reaches integrations you've explicitly attached to it. Flip Use all workspace integrations in an agent's Integrations card and its effective set becomes every active workspace integration automatically — connect something new and the agent can use it on its next run, no attach step needed.

With the flag on, each workspace integration still renders as its own switch so you can exclude specific ones without disconnecting them workspace-wide. Creating a trigger against an excluded integration turns it back on for that agent — wiring the trigger is a clear enough signal that you want the access back.

The Levain agent ships with this flag on, since it's meant to reach whatever you've connected without you managing attachments one by one.

Script it with PUT /api/v1/agents/{agent_id}/integrations/workspace-access ({"enabled": bool}). GET /api/v1/agents/{agent_id}/integrations reports each row's source — attached, workspace, or excluded.

Platform apps

Platform apps go further than tool-and-event integrations. Connect one and Levain starts a continuous data sync — verified webhooks plus scheduled backfills — from the provider into your workspace. That data powers the Metrics page and can trigger agents the moment a notable event lands.

The platform apps available at launch are Stripe, Shopify, Google Ads, and Meta Ads. Connecting any of them:

• Starts syncing the provider's data (charges, orders, ad metrics) into your workspace in real time.
• Unlocks the KPIs for that provider on the Metrics page.
• Makes app-event triggers available — e.g. stripe.invoice.payment_failed, shopify.orders/create. See the Automation guide for wiring them up.
• Provides built-in agent templates pre-wired to act on that data (revenue analysis, dunning recovery, order operations, ad optimisation), plus ready-to-adopt managed analysts for Stripe and Shopify if you'd rather adopt than build.

Platform apps appear as tiles on the Integrations page alongside Slack, GitHub, and MCP servers. The connect flow is the same: click the tile, walk through the provider's OAuth in your browser. Shopify additionally asks for your store domain.

Once connected, the tile shows per-stream sync status (Live / Syncing / Paused / Error) and the timestamp of the last successful sync.

Data privacy

Platform apps sync customer data — orders, checkouts, contact details — into your workspace. Levain tracks privacy requests against that data from two sources:

• Platform-initiated. A provider's mandatory compliance webhooks (e.g. Shopify's customers/redact, customers/data_request, shop/redact) land automatically as your workspace receives them.
• Manual erasures. Request deletion of one customer's stored data yourself, by their platform customer id or email:

curl -X POST https://api.levainlabs.com/api/v1/privacy/erasures \
  -H "Authorization: Bearer $LEVAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform": "shopify", "email": "customer@example.com"}'

Erasures require the admin role. Deletion runs asynchronously — typically minutes, always within 30 days.

Every request, platform-initiated or manual, moves through the same states:

Poll GET /api/v1/privacy/requests/{request_id} for one request, or GET /api/v1/privacy/requests for the workspace's full history. For a customers/data_request (an access request, not a deletion), GET /api/v1/privacy/requests/{request_id}/export compiles the customer's stored contact fields and order/checkout summaries so you can hand them back.

Inbound webhook sources

Some integrations connect by receiving events rather than by OAuth. Segment is the first: connecting mints a per-workspace ingest URL and HMAC signing secret that you paste into Segment as a Webhook destination. From that point every Segment track, identify, and page call is signature-verified, normalized, and published into your workspace's app-events pipeline.

To connect:

1. Open Integrations and click the Segment tile.
2. Copy the ingest URL and the signing secret — the secret is shown only once. Keep it safe — you can rotate it at any time from the tile's Setup action.
3. In Segment, add a Webhook destination pointed at the ingest URL and set the signing secret.

Segment events land in the same pipeline as platform-app data. App-event triggers for Segment events are not yet available.

Connect from the dashboard

The Integrations page in the sidebar shows everything that's already connected and a tile catalogue of providers to add.

• Slack and GitHub are first-class tiles — click connect and walk through the provider's authorisation in your browser. GitHub's flow includes the App install screen so you can pick which repos to grant.
• Platform apps (Stripe, Shopify, Google Ads, Meta Ads) — connect the same way; the platform starts syncing data automatically on completion.
• Segment — no OAuth. Click the tile, copy the ingest URL and signing secret, then configure a Webhook destination in Segment.
• MCP servers — Notion, Cloudflare, and a growing catalogue — install with the same one-click flow. For anything not in the catalogue, the Custom MCP server tile takes any OAuth-protected MCP URL and registers Levain as a client automatically.

Connected integrations show a status pill (active, pending, expired) and a Disconnect button. Disconnecting an integration cleanly removes the credentials and any agent access that relied on them.

Credentials stay on the platform

Tokens and credentials for every integration are encrypted at the workspace level. Agents call tools by name; Levain handles the authorisation, refresh, and revocation behind the scenes. Your agent recipe doesn't carry secrets, and rotating an integration is one click in the dashboard.

From the API

You can list connected integrations, fetch available providers, and disconnect from outside the dashboard. The Integrations API reference covers the endpoints. The initial connect flow is dashboard-only because it ends in a provider authorisation page that needs a browser.

Next

• The Tools primitive explains how a connected capability becomes callable for an agent.
• Set up a trigger so events from your integration fire an agent.
• View Metrics to see the KPIs unlocked by your connected platform apps.