connectors

External MCP servers and OpenAPI integrations the agent can call (Notion, Stripe, Bitly, Google, …). Each connector contributes tools at chat time.

connectors — Connectors

External MCP servers and OpenAPI integrations the agent can call (Notion, Stripe, Bitly, Google, …). Each connector contributes tools at chat time.

Section key connectors · Shape object · Tier All plans
Edit in the dashboard: Connectors page
Related: Connectors guide

Fields

Field	Required	Type	Allowed values / constraints	Default	Description
connectors	no	array of object	—	—	List of active MCP/tool connectors. Item fields below.

connectors items

List of active MCP/tool connectors.

Field	Required	Type	Allowed values / constraints	Default	Description
name	yes	string	—	—	Human-readable connector name.
mcp_server_url	yes	string	—	—	MCP server URL.
source	yes	enum	one of manual, catalog, openapi, graphql, database	—	How this connector was added.
tag	no	string	—	—	Catalog tag (for source=‘catalog’).
connector_id	no	string	—	—	Catalog connector ID.
auth_type	no	string	—	—	Authentication method: ‘none’, ‘token’, ‘header’, ‘oauth’, etc.
auth_values	no	object	—	—	Key/value pairs holding auth credentials (e.g. {“api_key”: “sk-…”}). Secret-bearing values (api_key, *token, *_secret, basic_pass, header values, …) are encrypted at rest and decrypted transparently on read; structural fields (header names, api_key_in, client_id, *_url) stay plaintext.
credential_status	no	string	—	—	‘none’ = no credentials; ‘stored’ = credentials have been saved.
oauth_status	no	string	—	—	OAuth flow status: ‘pending’, ‘connected’, ‘error’, etc.
oauth_token_ref	no	string	—	—	Internal reference to the stored OAuth token.
key_verified	no	boolean	—	—	Whether the API key has been test-verified successfully.
key_verified_at	no	string	—	—	ISO timestamp of last successful key verification.
connected_via	no	string	—	—	Human-readable summary of how the connection is authenticated.
instructions	no	string	—	—	Extra instructions injected into the system prompt for this connector’s tools.
disabled_tools	no	array of string	—	—	Names of tools from this connector that should be hidden from the agent.
pinned_params	no	object	—	—	Creator-pinned tool parameters, keyed by raw tool name → { paramName: value }. Each pinned value is hard-set at tool-call time (overrides whatever the model supplies) and stripped from the schema the model sees. When the connector is exposed to power-users, power-users see only a ‘set by creator’ indicator — never the value — and cannot edit it. See project_tool_param_pinning / $lib/shared/pinned-params.
agent_user_access	no	enum	one of own_auth, locked, hidden, owner_only; Pro+	—	Power-user access policy for this connector — the canonical field; set this instead of the legacy booleans. ‘own_auth’: listed on each power-user’s connectors dashboard and every power-user authorizes their OWN account (the owner copy never runs in power-user sessions). ‘locked’: shown read-only on power-user dashboards and runs in power-user chats with the OWNER’s credentials (power-users can’t edit or replace the auth). ‘hidden’ (default): invisible to power-users but still runs in their chats with the owner’s credentials. ‘owner_only’: never available in power-user sessions at all.
expose_to_agent_users	no	boolean	Pro+	—	LEGACY mirror of agent_user_access === ‘own_auth’. Kept in sync automatically on save — set agent_user_access instead.
expose_as_required	no	boolean	Pro+	—	When agent_user_access is ‘own_auth’, whether the connector is mandatory for power-users (chat CTA banner is non-dismissable until connected).
keep_as_is_in_agent_user_instance	no	boolean	Pro+	—	LEGACY mirror of agent_user_access === ‘locked’. Kept in sync automatically on save — set agent_user_access instead.
description	no	string	—	—	Optional human-readable description of what this connector provides.
logoUrl	no	string	—	—	URL of the connector’s logo for display in the dashboard.
collapsed	no	boolean	—	—	UI hint — start this entry collapsed in the dashboard.
openapi_spec_hash	no	string	Pro+	—	SHA-256 hash of the OpenAPI spec (for source=‘openapi’). Used to detect spec changes.
openapi_info	no	object	Pro+	—	Extracted OpenAPI info object (title, version, description, specVersion).
openapi_servers	no	array of string	Pro+	—	Server URLs from the OpenAPI spec.
openapi_auth	no	object | array	Pro+	—	Parsed auth configuration from the OpenAPI spec.
openapi_operations	no	object | array	Pro+	—	Parsed operations from the OpenAPI spec.
openapi_sdk	no	object	Pro+	—	Generated SDK metadata.
event_handlers	no	array of object	Business+	—	Per-connector MCP event handlers. Each handler matches inbound MCP events by name (and optionally by a payload-filter JSONPath) and either runs sandboxed code, invokes a built-in tool, or fires off an agent run. See project_mcp_event_handlers. Item fields below.

connectors.event_handlers items

Per-connector MCP event handlers. Each handler matches inbound MCP events by name (and optionally by a payload-filter JSONPath) and either runs sandboxed code, invokes a built-in tool, or fires off an agent run. See project_mcp_event_handlers.

Field	Required	Type	Allowed values / constraints	Default	Description
id	yes	string	—	—	Stable 1–32 char id. Used as the dedup key in the event audit log.
name	no	string	—	—	Human-readable label (max 120 chars).
enabled	no	boolean	—	—	Off-switch. When false, the handler is registered but will not fire when the event matches.
collapsed	no	boolean	—	—	UI hint.
event_match	yes	object	—	—	Which inbound event(s) this handler fires for. Item fields below.
payload_filter	no	string	—	—	Optional JSONPath expression filtering the event payload (max 400 chars).
handler	no	object	—	—	What to do when the handler matches. Item fields below.
pipeline	no	object	—	—	Unified incoming-event pipeline for this event (pre-processor → interpreters → classifier → context → notes). When present it supersedes the legacy ‘handler’ action. The event_match/payload_filter above remain the selector. See $lib/shared/event-pipeline. Item fields below.

connectors.event_handlers.event_match fields

Which inbound event(s) this handler fires for.

Field	Required	Type	Allowed values / constraints	Default	Description
type	yes	enum	one of name	—	Currently only ‘name’ matching is supported.
value	yes	string	—	—	MCP event name (or a wildcard like ‘foo.*’), max 200 chars.

connectors.event_handlers.handler fields

What to do when the handler matches.

Field	Required	Type	Allowed values / constraints	Default	Description
kind	yes	enum	one of code, tool, agent	—	Handler type: ‘code’ (runs sandboxed Python or JavaScript), ‘tool’ (invokes email_send/email_read/email_status), or ‘agent’ (triggers an agent run with a prompt template).
language	no	enum	one of python, javascript	—	For kind=‘code’.
code	no	string	—	—	For kind=‘code’: source body (max 50 000 chars). Must export an async handle(input, ctx) function.
timeout_seconds	no	integer	min 1; max 30	—	For kind=‘code’: optional per-invocation timeout.
tool_name	no	string	—	—	For kind=‘tool’: name of the built-in tool to invoke (email-tool allowlist only — see project_mcp_event_handlers).
input_mapping	no	object	—	—	For kind=‘tool’: map of tool-input-name → JSONPath into the event payload.
prompt_template	no	string	—	—	For kind=‘agent’: template prompt that fires the agent (max 20 000 chars). Supports {{event.*}} placeholders.
chat_session_strategy	no	enum	one of new, per-source	—	For kind=‘agent’: whether each event spawns a fresh chat session or reuses one keyed on source_id_path.
source_id_path	no	string	—	—	For kind=‘agent’ + per-source: JSONPath into the event payload identifying the source.

connectors.event_handlers.pipeline fields

Unified incoming-event pipeline for this event (pre-processor → interpreters → classifier → context → notes). When present it supersedes the legacy ‘handler’ action. The event_match/payload_filter above remain the selector. See $lib/shared/event-pipeline.

Field	Required	Type	Allowed values / constraints	Default	Description
preProcessor	no	object	—	—	Item fields below.
interpreters	no	array of object	—	—	Item fields below.
classifier	no	object	—	—	Item fields below.
context	no	string	—	—
notes	no	string	—	—
outputContract	no	object	—	—	Optional post-LLM output contract: parse the agent reply as JSON and (optionally) validate it against schema; enforced on MCP connector events. See $lib/shared/event-pipeline OutputContractConfig. Item fields below.

connectors.event_handlers.pipeline.preProcessor fields

Field	Required	Type	Allowed values / constraints	Default	Description
enabled	no	boolean	—	—
language	no	enum	one of python, javascript	—
code	no	string	—	—

connectors.event_handlers.pipeline.interpreters items

Field	Required	Type	Allowed values / constraints	Default	Description
name	no	string	—	—
matchType	no	enum	one of json_fields, regex	—
matchFields	no	string	—	—
matchRegex	no	string	—	—
matchRegexFlags	no	string	—	—
hint	no	string	—	—

connectors.event_handlers.pipeline.classifier fields

Field	Required	Type	Allowed values / constraints	Default	Description
enabled	no	boolean	—	—
prompt	no	string	—	—
actionAllowlist	no	array of string	—	—

connectors.event_handlers.pipeline.outputContract fields

Optional post-LLM output contract: parse the agent reply as JSON and (optionally) validate it against schema; enforced on MCP connector events. See $lib/shared/event-pipeline OutputContractConfig.

Field	Required	Type	Allowed values / constraints	Default	Description
format	yes	enum	one of json	—
extract	no	enum	one of fenced, whole	—
schema	no	object	—	—
on_invalid	no	enum	one of error, store_raw	—
forward_tool	no	string	—	—