> ## Documentation Index > Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](/sidebar-menu/connectors)\ **Related:** [Connectors guide](/sidebar-menu/connectors) ## 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 | — | — | |