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?) (pass thread_ts from a prior call to reply in a thread) and list_channels(). 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 eight tools: list_repositories, list_issues, get_issue, create_issue, comment_on_issue, update_issue, create_pull_request, and list_pull_requests. 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"]}

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.

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.