Connectors

Connect your agent to external services and APIs via MCP servers, OpenAPI specs, and GraphQL endpoints.

Field reference: connectors and composio_connectors — every field, type, default, and tier for this page.

Connectors extend your agent with access to external services. You can connect to any service that exposes an MCP (Model Context Protocol) server, an OpenAPI specification, or a GraphQL endpoint. Once connected, the agent can call the service’s tools and APIs during conversations.

The dashboard page is titled Connectors.

Prefer worked, service-by-service walkthroughs (Slack, GitHub, Google Calendar, HubSpot) and the full database-connector guide? See the companion Connectors reference page.

Connector types

Type	Description
MCP - Provider	Pick from the built-in catalog of vendor-provided MCP servers.
MCP - Managed	Use a managed Composio integration (500+ services).
MCP - Manual	Connect to an arbitrary MCP-compatible server by URL.
OpenAPI	Import an OpenAPI 3.x spec. Agentheya generates a typed SDK and two LLM tools: one to search the API docs and one to execute calls.
GraphQL	Point at a GraphQL endpoint; the agent gets a tool to issue queries and mutations.
Database	Connect your own database (PostgreSQL, MySQL, SQL Server, BigQuery, and more). Agentheya generates a safe, read/write-scoped data layer in front of it, and you choose table-by-table what the agent can read or write. Shown only when database connectors are enabled on your deployment.

Adding an MCP connector

Use the buttons below the connectors list:

• Add MCP Provider — opens the built-in catalog of vendor-provided servers.
• Add MCP Managed — opens the Composio toolkit picker (500+ managed integrations).
• Add MCP Manual — opens a small dialog that asks only for a Name and an MCP Server URL. Authentication is not configured here — you set it up afterwards, on the connector’s card.

Catalog and managed connectors are added straight to the list. A manual connector lands on the list as a card you expand to configure authentication and connect. Reorder the cards at any time by dragging them.

Connecting a manual MCP server

Expand the new card and open the Authentication dropdown. It offers three modes, each paired with an Authorize button — there is no separate “Test Connection” button; Authorize both connects and discovers the server’s tools.

Mode	What it does
Automatic	Tries the server with no auth first; if the server demands credentials, it automatically probes for OAuth and, when found, sends you through the sign-in flow. The best first thing to try.
Headers	Add one or more request headers — e.g. Authorization: Bearer sk-… or X-Api-Key: …. Click Add Header for extra pairs.
OAuth	Configure an OAuth 2.0 flow yourself (fields below).

Click Authorize. A progress trace shows the connection attempt, the server’s response, and how many tools were discovered; on success the card shows a Connected badge.

Manual OAuth fields

The OAuth mode exposes these fields — all optional, so you can leave them blank to let Agentheya auto-discover the endpoints from the server’s metadata:

Field	Notes
Client ID / Client Secret	Your OAuth app’s credentials.
Authorization URL	e.g. https://provider.com/oauth/authorize.
Token URL	e.g. https://provider.com/oauth/token.
Scopes	Space-separated, e.g. read write openid.
Extra Authorization Parameters	Query-string flags appended to the authorization URL — Google, for example, needs access_type=offline&prompt=consent to issue a refresh token.

Register the OAuth Callback URL shown on the card — https://<your-domain>/api/mcp-oauth/callback — as the redirect/callback URI in your OAuth app on the provider’s side, or the sign-in is rejected.

Browsing the catalog

Add MCP Provider opens a full-page catalog of 150+ vendor-provided MCP servers. Use the search box (it matches name and description) to narrow the list. Each tile shows the service, a one-line description, and an auth badge:

• Ready — no authentication required. Picking it adds the connector and authorizes it immediately.
• OAuth — you complete a sign-in flow after adding.
• API Key — you paste a key or token on the card after adding.

Click the ℹ (info) icon on a tile for a details popup — full description, the capabilities the server provides, and a link to the vendor’s documentation. Click the tile body to add it. If a connector with the same display name already exists, you’re asked for a short suffix so the two can coexist.

Composio toolkits

Add MCP Managed opens the Composio toolkit picker. Search filters the list (results are paginated — use Load more for the next page). Click the ℹ icon on a tile to preview its capabilities — the exact tools the toolkit exposes, with names and descriptions — before committing, then click the tile to add it.

How you finish connecting depends on the toolkit:

• OAuth toolkits land on the list with an Authorize button; click it to complete Composio’s OAuth flow.
• API-key toolkits land as a Not Connected placeholder with a Set API Key button. Enter your key in the popup and the connector is created and stored — the key is never exposed to the agent.

For email management, prefer the first-party Gmail / Outlook integration on the Email page rather than a Gmail/Outlook connector here. It sends as your real identity and gives the agent curated gmail_* / outlook_* tools (search, read, draft, label/organise) — better suited to ongoing inbox management than the generic MCP connector path.

Adding an OpenAPI connector

OpenAPI connectors require the Pro plan. On lower plans the Add OpenAPI button stays visible but shows a lock and opens an upgrade prompt.

1. Click Add OpenAPI and give the connector a Name and the spec URL.
2. Agentheya fetches the spec, generates an SDK artifact, and persists a summary (operation count, servers, auth schemes) on the card.
3. Configure authentication (API key, Bearer token, or OAuth via DCR where the spec supports it).
4. Save.

Adding a GraphQL connector

1. Click Add GraphQL.
2. Enter a name and the GraphQL endpoint URL.
3. Save.

Adding a Database connector

Connect your own database and control exactly what the agent can see. Agentheya generates a safe, read/write-scoped data layer over your data — the agent never touches the database directly.

1. Click Add Database (shown only when database connectors are enabled on your deployment).
2. Choose the database type — PostgreSQL, Citus, CockroachDB, SQL Server, and BigQuery are supported out of the box; MySQL, MariaDB, Oracle, and Snowflake require additional connector support to be enabled on your deployment.
3. Give the connector a name and paste the connection string (stored encrypted). Click Connect & list tables to discover the schema — nothing is exposed yet.
4. For each table, enable the operations the agent may run (read / insert / update / delete), optionally hide columns, and add an optional row filter (a boolean expression in JSON, e.g. { "tenant_id": { "_eq": 42 } }) so the agent only ever sees the rows you allow.
5. Add tags and a short “when to use it” note so the agent knows which table to reach for, then click Apply & generate agent tools.

Column-level hiding is auto-discovered on PostgreSQL-family databases only — there the columns are listed for you to click; for other database types you type the column names to hide. Row filters work on every supported database.

Exposure is deny-by-default and enforced at the GraphQL layer, not just in the prompt: untracked tables are invisible, hidden columns never appear, and the row filter applies to reads and writes alike. The agent always queries under a restricted role bound to exactly your grant. Enable only read for a query-only agent. The agent then gets graphql_search_schema (to find the right table/fields, enriched with your tags and notes) and graphql_execute (to run the query or mutation, scoped to your grant). Removing the connector disconnects it and deletes the stored credentials; your database itself is untouched. See the full walkthrough in Connectors → Database connector.

Authentication

Connectors support:

Method	How to configure
Automatic (manual connectors)	Tries no-auth, then auto-discovers OAuth if the server requires it — see Connecting a manual MCP server.
No auth	Leave the auth fields empty.
Headers	Add request headers (e.g. Authorization: Bearer <key>, X-Api-Key: …).
OAuth 2.0	For catalog / managed / OpenAPI connectors that advertise OAuth — follow the on-screen authorisation prompt. For manual connectors, use the OAuth panel and register the callback URL. Composio handles the OAuth flow for managed integrations.

Managing tool capabilities

Every MCP connector card has a Capabilities button (and an inline tools list) that opens the connector’s discovered tools. From there you can:

• Discover / Rediscover — query the server for its current tool list. Click Rediscover whenever the upstream server adds or changes tools; there is no separate “test connection” step. (For OpenAPI connectors, re-fetch the spec on the card instead.)
• Enable or disable individual tools — toggle each tool on or off, or use Enable all / Disable all. Disabled tools are hidden from the agent entirely — it cannot call them. The Capabilities button shows an enabled / total count.
• Pin tool parameters — expand a tool, type a value into a parameter, and click away to pin it. The agent then always calls that tool with the pinned value and never sees the field; clear the box to unpin. This is the connector-tool equivalent of locking a parameter — see tool-parameter pinning for the same idea applied to built-in tools, including the default and append modes.

Each connector card also carries:

• Instructions — free-form text attached to the connector in the agent’s system prompt, useful for telling the agent when to prefer this connector over others.
• A suffix (tag) — a short label that disambiguates two connectors sharing a display name.

Subscriber access

On the Pro plan and above, each connector card gains a Subscriber access selector that decides how the connector behaves for the subscribers who resell or embed your agent. There are four options (fewer for no-auth connectors, where credential-based choices don’t apply):

Option	Effect
Owner only	Only your own sessions use the connector; it is never loaded in subscriber chats.
Hidden — uses your credentials	Subscribers never see the connector, but the agent still uses it in their chats with your credentials.
Visible & locked — uses your credentials	Subscribers see the connector on their dashboard as locked and read-only; it runs with your credentials and they can’t edit or replace the auth.
Subscribers connect their own account	Listed under Suggested on each subscriber’s connectors dashboard. Every subscriber authorizes their own account — your credentials are never used in their chats.

When you choose Subscribers connect their own account, a Required checkbox appears — tick it to block a subscriber’s chat until they’ve connected the account.

Subscribers manage their own connections from the Connectors page in their personal dashboard (agentheya.com/agent/{name}/dashboard/connectors); their credentials are stored separately and scoped to their own sessions.

Event handlers

A manual MCP connector card can react to inbound events from that server. Under Event Handlers, click Add Event, name it, and enter the exact event name to listen for (e.g. notifications/resources/updated) plus an optional JSONPath-lite payload filter so the handler only fires on matching events. Each handler runs the same event pipeline used elsewhere — run code, call a tool, or hand the event to the agent.

Events reach the handler two ways: a webhook POST to /api/mcp-event/<connector_name> authenticated with one of the agent’s API keys, or the persistent MCP listener daemon when the server emits notifications. Event handlers are available on all plans; autonomous execution is cost-contained by per-instance ingress budgets and per-call charges rather than by tier.

Examples

Hello world — a public weather MCP. Click Add MCP Manual, give it a name and a public weather MCP server’s URL. Expand the card, leave Authentication on Automatic, and click Authorize — the tools appear. Now your agent can answer “what’s the forecast in Berlin?” by calling the connector. The fastest way to give your agent a new capability.

Simple — a SaaS integration via Composio. Click Add MCP Managed, pick (say) Google Calendar from the catalog, and click Authorize to complete the OAuth prompt — Composio handles the flow. Your agent can now read and create calendar events on the connected account. No URL, no headers, no spec — just authorise and go.

Medium — your own REST API via OpenAPI. Add an OpenAPI connector and paste your API’s spec URL. Agentheya generates a typed SDK plus two tools — one to search the API docs, one to execute calls — so the agent can discover the right endpoint and call it correctly. Configure a Bearer token for auth, add an Instruction like “Use this for anything about customer orders,” and toggle off any operations you don’t want the agent touching (e.g. deletes).

Complex — a multi-connector agent with routing instructions. Wire up three connectors: your orders API (OpenAPI), a shipping provider (MCP catalogue), and a GraphQL endpoint for your product catalogue. Give each a Tag and an Instruction that tells the agent when to prefer it — “orders API for order status; shipping MCP for tracking numbers; catalogue GraphQL for product availability.” The agent now routes each user question to the right backend, and you’ve toggled off any destructive operations so it can read freely but only write where you’ve allowed. Layer per-tool toggles so the same connector exposes a safe read-only subset to subscribers while you keep full access.

System-pushing — per-user connected accounts at scale. For an agent you resell, set each connector’s Subscriber access to Subscribers connect their own account so each subscriber connects their own accounts (their CRM, their calendar, their inbox) from their personal dashboard. The agent then operates against each user’s own credentials, scoped to their sessions — one agent, many isolated integrations, no shared keys. Combine with pricing tiers that gate which connectors each tier of subscriber can use.

Manage via the Management MCP

This page can be configured programmatically through the Management MCP — useful for AI agents and CI pipelines.

Endpoint	https://manage.agentheya.com/mcp
Tool	config.set
Section	connectors
Schema (HTTP)	GET /api/manage-mcp/schema/connectors

Example:

{
  "tool": "config.set",
  "owner_id": "<your owner_id>",
  "agent_id": "<your agent_id>",
  "section": "connectors",
  "data": { /* see schema for accepted fields */ }
}

Partial updates are supported — only the fields you include are changed. Call config.get to read the current values and schema.get (or the HTTP schema URL above) to see the full field list.