> ## 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
> Connect your agent to external services and APIs via MCP servers, OpenAPI specs, and GraphQL endpoints.
**Field reference:** [`connectors`](/reference/connectors) and [`composio_connectors`](/reference/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](/sidebar-menu/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](#browsing-the-catalog) of vendor-provided servers.
* **Add MCP Managed** — opens the [Composio toolkit picker](#composio-toolkits) (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:///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](/sidebar-menu/email-addresses#connect-your-own-mailbox-gmail-outlook) 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](/sidebar-menu/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](#connecting-a-manual-mcp-server). |
| **No auth** | Leave the auth fields empty. |
| **Headers** | Add request headers (e.g. `Authorization: Bearer `, `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](/sidebar-menu/tools#wrapping-a-built-in-tool) 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](/sidebar-menu/users) 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/` 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](/sidebar-menu/pricing) 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](/manage-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`](https://agentheya.com/api/manage-mcp/schema/connectors) |
Example:
```json theme={null}
{
"tool": "config.set",
"owner_id": "",
"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.