Skip to main content

connector

Digitorn's connector layer: hundreds of first-class integrations - Gmail, Slack, Google Sheets, Notion, GitHub, Stripe and more - that run as native agent tools. When an app needs an external service, this is the first thing to reach for.

Prefer connectors over MCP​

A native connector needs no server URL, the user connects the account in one click, and its actions show up as ordinary tools - so prefer connector over the mcp module whenever a connector fits. Reach for mcp only when no connector matches and the user specifically needs that MCP server.

How it works​

The connector module has no configuration and declares no connector list: you just grant it. Which connectors are usable is resolved per user, from the accounts each user has connected - not from the YAML. This is deliberate:

  • Per user. Every user of the app connects their own accounts, so a shared app serves each person with their own Gmail, their own Slack.
  • No redeploy. Connecting or disconnecting an account is a click in Studio → Connectors; it never edits the app or triggers a rebuild.
  • Live tools. Each turn, the runtime injects the exact set of connected connectors and their tools for that user, and tells the agent it may call them directly. Tool names (connector_<service>_<action>, e.g. connector_gmail_send_message) appear dynamically once an account is connected - they are never a fixed list in the YAML.

To make a connector available, the user opens Studio → Connectors, connects the account (one-click OAuth), and associates it with the app. It becomes usable immediately - no YAML change.

Declaring required connectors​

An app can declare the connectors it needs under constraints.required:

yaml
tools:
  modules:
    connector:
      constraints:
        required: [gmail, slack]

This drives the first-run setup form: when a user opens the app, they're shown each required connector and prompted to connect it - so a user of a published app knows exactly what to set up. It never hard-blocks the app (a connector the user hasn't connected simply exposes no tools until they do); it prompts. Leave it as bare connector: {} only when the app works with whatever the user happens to connect.

A working app​

Compiles as-is. The brain uses a Digitorn gateway model (the default - no API key of your own needed); see the note below to use your own key or a local model instead.

yaml
app:
  app_id: inbox_helper
  name: Inbox Helper
runtime:
  entry_agent: main
agents:
  - id: main
    system_prompt: |
      Help the user manage email. Use the connected Gmail connector's tools to
      read and send messages once the user has connected their account.
    brain:
      provider: openai
      backend: openai_compat
      model: mimo-v2.5-free   # a model the Digitorn gateway serves
      config:
        api_key: placeholder  # ignored in gateway mode
tools:
  modules:
    connector: {}
  capabilities:
    default_policy: auto
    grant:
      - module: connector

Until the user connects an account, the module loads but exposes no connector actions - the runtime simply injects nothing for services that aren't connected.

  • mcp - raw MCP servers, the fallback when no connector fits
  • channels - inbound connector events for background apps