Integrations

Overview

The Integrations tab is where you grant your agent access to third-party services. It hosts two kinds of integrations side-by-side:

• Native connectors — first-party integrations we build and maintain (Google Workspace today; more on the way). Tools execute server-side on our platform using OAuth tokens, with per-service toggles (Calendar, Drive, Docs, …).
• Custom MCP servers — any Model Context Protocol compatible URL you want to connect (GitHub, Linear, Notion, your own internal APIs). Tools execute remotely via the MCP protocol, with per-tool toggles.

Both kinds appear together as cards on the Integrations tab and use the same status/management UX.

Native Connectors vs Custom MCP

If we ship a native connector for a service you need, use it — it's faster, has tighter scope control, and is pre-vetted. Otherwise, custom MCP gives you full flexibility.

How It Works

Native connectors

1. You pick a connector (e.g., Google) from the catalog and select which services to enable (Calendar, Drive, Docs)
2. You complete the OAuth flow in a popup
3. We store the OAuth tokens encrypted in Supabase Vault and auto-refresh them
4. Each enabled service exposes a set of tools the agent can call (e.g., google_calendar_create_event, google_drive_search)
5. When the agent calls a tool, our backend executes the request against the provider API using the stored token — the token is never sent to the LLM

Custom MCP servers

1. You add a remote MCP server URL on the Integrations tab
2. The platform connects to the server and discovers the tools it exposes
3. Discovered tools are added to your agent's available toolset
4. When the agent calls one of those tools, your auth token is attached as a request-level credential — never inserted into the conversation
5. The tool's response is returned to the agent

Native:  Agent calls "google_calendar_create_event"
         → Our backend calls Google's API with your OAuth token
         → Result returned to the agent

MCP:     Agent calls "create_issue" (from your GitHub MCP server)
         → The model provider attaches your bearer token and dispatches
         → Result returned to the agent

Connecting an Integration

1. Go to the Integrations tab on your agent's detail page
2. Click Add Integration
3. Pick from the catalog:
   • A native connector card (e.g., Google) — opens a service-selection step
   • Custom MCP — opens the MCP setup form

Connecting Google Workspace

1. Click the Google card in the catalog
2. Tick the services you want to enable:
   • Calendar — create, read, update, and search events
   • Drive — search and read files
   • Docs — read and edit documents
3. Click Connect and complete the OAuth popup
4. The connector card shows as Active with a chip per enabled service

You can enable additional services later from the connector's Settings drawer. Adding a service that needs new scopes will prompt a re-authorization.

Connecting a Custom MCP Server

1. Click Custom MCP in the catalog
2. Fill in:
   • Display name — A friendly label (e.g., "GitHub", "Internal CRM")
   • Server URL — The MCP server endpoint
   • Authentication — Choose Bearer token, OAuth, or None (see below)
3. Click Connect

The platform validates the connection and discovers available tools. Once connected, the integration appears as a card alongside your native connectors.

Authentication Methods

For native connectors, OAuth is the only option — we manage the entire flow including refresh.

Choosing What to Expose

You don't have to expose everything an integration offers.

• Native connectors — toggle individual services on/off via the Settings drawer. Disabled services hide all their tools from the agent. The card shows a chip per enabled service.
• Custom MCP — toggle individual tools on/off via Edit. Disabled tools don't appear in the agent's toolset.

This is useful when an integration offers both safe read-only operations and destructive write operations — expose just what you trust the agent to use.

Connection Status

Each integration card shows a status badge. The same set of statuses applies to both native connectors and custom MCP:

Managing Integrations

Each integration card has actions in its menu:

Security

The model can't read or echo your integration tokens — they aren't part of any prompt or message it sees.

Best Practices

• Prefer native connectors when available — they're faster, scope-controlled, and pre-vetted
• Enable only the services or tools you need — fewer tools = clearer agent decisions and tighter security
• Use descriptive display names — "GitHub (Production)" is clearer than "github"
• Test after rotating tokens — click Test to verify the new token works before the next agent run
• Disable instead of deleting — if you're temporarily not using an integration, disable it to keep configuration around for later
• Reconnect when adding native services — adding a service that needs new OAuth scopes will prompt re-authorization; the existing token won't have the new permission

What's Next?

• Credentials — Store passwords and API keys for login forms
• Context & Configuration — Configure skills, instructions, and tools
• Agent Settings — Centralized agent configuration