Connectors

Connectors are external user accounts or data sources, such as Gmail, Outlook, Calendar, Drive, Notion, and Google Sheets.

These examples assume an initialized configure client and a profile from the Quick Start; token is the user's Continue-with-Configure session token, not your sk_ key.

Connector management is separate from model tools:

const connectors = await configure.connectors.list(token);

When a connector is connected and allowed for the turn, enable its model tool explicitly:

const tools = profile.tools({
  connectors: ["gmail", "calendar", "drive", "notion", "sheets"],
});

On the hosted MCP server, connector tools are listed automatically for linked users with the connector enabled; failed calls fail closed and configure_connect mints the reconnect link. No code is needed.

Connector-backed model tools:

• configure_gmail_search
• configure_email_search when outlook is enabled
• configure_calendar_get
• configure_drive_search
• configure_notion_search
• configure_sheets_search
• configure_sheets_read

Multiple Gmail Accounts

Multiple Gmail accounts are enabled by default in every hosted Configure sign-in. Developers do not set a feature flag or change their integration. Gmail tools take an optional account argument: a connected account ID or the account's email address:

• configure_gmail_search with account omitted searches every connected Gmail account, deduplicates results, and lists the inboxes searched in accounts_searched. If some accounts fail while others succeed, results are still returned with partial: true. Pass account to search one inbox.
• configure_email_send with account omitted sends from the user's default Gmail account. Pass account to send from a specific connected account; the response includes from_account.

Each email result carries an account object (id, email) identifying which inbox it came from. Users add and remove Gmail accounts in hosted Configure UI; when the default account is removed, a remaining account is promoted automatically.

Gmail And Outlook

Outlook is opt-in. Include outlook in the runtime connector list, then use configure_email_search to search every permitted Gmail and Outlook account. Omit provider and account for broad search. Each result identifies its provider and account; accounts_searched reports coverage, and partial: true means the agent must not claim every inbox was checked.

For sending, Gmail-only runtimes keep the existing default Gmail behavior. An Outlook-aware runtime must provide provider or account when both providers are available; Configure returns email_account_selection_required instead of choosing silently.

Actions

Actions are explicit and write to external services. Expose the actions your app supports when your product has the corresponding hosted approval or confirmation path:

const tools = profile.tools({
  actions: ["email.send", "calendar.create_event", "sheets.values_update", "sheets.values_append"],
});

Action model tools:

• configure_email_send
• configure_calendar_create_event
• configure_sheets_values_update
• configure_sheets_values_append
• configure_sheets_create_spreadsheet
• configure_sheets_add_sheet

Do not execute action tools unless the user grant, explicit action confirmation, and your product policy allow the action for that turn. When you drive the model loop with the SDK, profile.executeTool() throws a ConfigureError if an enabled action cannot run. Inspect error.suggestedAction: it tells you what to do. When it is connect_tool, the app is not connected, so send the user to connect instead of retrying. Other failures carry their own signal, for example check_permissions for a missing grant or reauthenticate for an expired token; route each to the matching hosted surface:

import { ConfigureError } from "configure";

try {
  return await profile.executeTool({ name: call.function.name, arguments });
} catch (error) {
  if (error instanceof ConfigureError && error.suggestedAction === "connect_tool") {
    // app is not connected: send the user to connect, do not retry
    return promptUserToConnect();
  }
  throw error;
}

On the hosted MCP server this failure is handled for you: the tool result carries a connect_url and configure_connect mints the link, as noted above.