Integrations

Connect your app to external services — anything that uses OAuth, API keys, or bearer tokens. Foundation runs the auth flow and stores the tokens; your app just manages connections and calls the capabilities you expose.

This page has two halves: Configure sets integrations up on the platform (no code), and Use in your app wires connection management into the frontend you're building.

Configure

Set integrations up on the platform side — in the dashboard or by asking your agent. No code required.

Connect a service

Add an integration and Foundation handles the auth flow end to end: OAuth redirects, token storage, and refresh tokens. You don't see or store secrets in your app.

Map capabilities

Each integration exposes capabilities — the methods you can call on the external service. A Google Calendar integration might expose:

• List events
• Create event
• Update event
• Delete event

Choose how capabilities are exposed

• REST API — your app's users call integration methods through your API
• MCP — AI agents use your integrations as tools
• AI Prompts — wire integrations into your prompt chains as tools

Control access

Integration access is governed by roles and scopes. You decide which users and which external agents can use which integrations.

Use in your app

The SDK manages connections — listing the catalog, connecting, checking status, disconnecting. Invoking an integration's capabilities (list events, etc.) happens through the surface you exposed in Configure (your REST API or MCP), not a direct SDK call. Full method signatures live in the SDK reference.

Show the catalog and connection state

const integrations = await foundation.integration.all()  // catalog + current connection state

Use all() rather than stitching list() and connections() yourself.

Connect a service

const result = await foundation.integration.connect(source)

if (result.url) {
  // open a popup or redirect, then refresh connection status when it returns
  window.open(result.url, 'connect', 'width=600,height=700')
}
// also handle immediate success / configuration responses

Disconnect

// only after explicit user confirmation
await foundation.integration.disconnect(source, configurationId)

Drop-in connect button (optional)

If you don't want to build the connect UI, use the web component:

import 'foundation-sdk/components'
;(window as any).__foundation = foundation

<foundation-connect integration-id="github-oauth"></foundation-connect>

It emits success, error, and close events. In Vue, configure isCustomElement for foundation-* tags.

Reference

• SDK methods used here: foundation.integration.all(), .connect(), .disconnect(), .status(), .connections() — see the SDK reference
• Roles & Scopes for per-integration access control
• MCP & API Overview for exposing capabilities as tools