Connectors

Connectors are the vendor-specific half of how Tale reaches other systems, and they are part of the platform rather than something an organisation assembles. Each one is a YAML file in the source tree that declares who it talks to, how it authenticates, and every action it can perform — which is why the catalog is identical in every deployment and why an upgrade is all it takes to move it forward. Read this when you want to know what a connector actually promises a caller, or when you are deciding between contributing one and hosting an MCP server.

The organisation-facing side — adding credentials, defaults, reconnecting a lapsed grant — is Connector credentials, and the catalog itself is Connectors.

How a connector is declared

Every connector is one directory under configs/platform/system/connectors/, named for its slug, holding a connector.yml and the icon the settings page renders. The slug is the directory name, the connector's declared name, and the first half of the node type an automation uses to place one of its actions — <connector>.<action>. Thirteen of these directories ship today.

The file opens with the connector's identity and its authentication contract, then lists the actions:

name: tavily
displayName: Tavily
description: Real-time web search and page extraction for AI research.
tags:
  - Search
allowedHosts:
  - api.tavily.com
auth:
  - method: api-key
actions:
  - name: search
    description: >-
      Search the open web via Tavily. Returns top results with title, URL,
      content snippet, and score.
    effects: read
    input:
      type: object
      required: [query]
      properties:
        query: { type: string, description: 'Natural-language search query.' }
        max_results: { type: number, description: 'Max results (1-10).' }
    output: '{ answer?: string, results: Array<{ title: string, url: string, content: string, score: number }> }'

allowedHosts is the egress boundary — an action body that reaches anywhere else is refused rather than proxied. A connector whose API lives at a customer address instead of a vendor one adds endpointMode: per-credential, and each credential then carries the origin its calls are built from; Confluence and Shopify are the two shipped cases.

What an action declares

An action is a contract, and every field of it is visible to the caller before the call happens:

• Name and description. The name completes the node type; the description is what an agent reads when it decides whether this action is the right one.
• Input. A JSON Schema — object type, required fields, and a description per property. Automations validate a node's configuration against it, and agents fill it from the same schema.
• Output. A signature describing the shape that comes back, so a workflow author knows what the next step can reference.
• Effects. Either read or write. Write actions gate behind the organisation's approval policy, and a call that cannot reach an approval decision is refused rather than performed ungated.

Actions resolve their credential at call time: the one the caller names, or the connector's default when the caller names none. That is the seam that lets the same automation run against a different account by pointing it at a different credential name. Mail sync and inbox triage are different on purpose — conversation.sync_mailbox and conversation.list_mailbox_messages walk every active credential on the connector so every connected mailbox is covered without naming each one.

The authentication methods

A connector declares the methods it accepts, and a credential is stored against exactly one of them. The four are fixed, because each one describes a different way a secret reaches the vendor.

Secrets are encrypted at rest in a single envelope and never travel back out to a caller. A listing shows a masked preview computed when the credential was written, so reading the credential list never touches ciphertext.

Registering an OAuth app

An oauth2 connector declares the vendor's authorize and token URLs plus the scopes it requests, and the deployment supplies the app those URLs authenticate against. Register this exact callback as an allowed redirect URI on the vendor side, built from the deployment's SITE_URL and any BASE_PATH prefix:

${SITE_URL}${BASE_PATH}/api/connectors/oauth2/callback

The client ID and secret for each connector come from the deployment environment, named per connector as CONNECTOR_OAUTH_<SLUG>_CLIENT_ID and CONNECTOR_OAUTH_<SLUG>_CLIENT_SECRET, with the slug upper-cased and its dashes turned into underscores. When SITE_URL is unset the consent flow refuses to start rather than guessing an origin from the request.

Choosing a surface

Two surfaces reach systems outside Tale, and the choice is about who owns and runs the bridge.

An MCP server is registered under Settings > API > MCP, and every tool it exposes joins the agent toolbelt beside connector actions, each with its own approval flag. The reference is MCP servers; the end-to-end build is MCP server from scratch.

Where this fits

A connector is a declared contract — hosts, authentication, and a typed action list — that ships with the platform and is fed by credentials the organisation owns. Read Connectors for what is in the catalog, Connector credentials for how those credentials are managed day to day, and MCP servers when the bridge you need has to be your own code.