# How connectors work

Last validated Oct 9, 2026

Connectors let agents call tools and query APIs through Aperture. Some connectors send each call to an upstream service, which is the external server that provides the tools or the API. Other connectors run their tools inside Aperture. Aperture has the following kinds of connectors:

* **Verified and custom connectors** send calls to an upstream Model Context Protocol (MCP) server or HTTP API. A verified connector starts from a preset in the Aperture registry. An admin defines a custom connector from scratch. Aperture can add the configured credentials to each call.
* **The `aperture` system connector and built-in connectors** run their tools inside Aperture. Built-in connectors, such as `Tailnet` and `TailnetSSH`, need an entry in your configuration. The `aperture` system connector does not.

Grants control access to all of them. This topic explains the model so you can predict how a connector behaves. For more about each kind, refer to [kinds of connector][docs-connectors-kinds]. For fields and values, refer to the [connectors reference][docs-connectors-reference].

## Connectors and providers

Aperture handles two kinds of agent traffic:

* [Providers][docs-aperture-set-up-providers] send large language model (LLM) requests to upstream model APIs.
* Connectors give agents tools and APIs.

A connector never serves model completions. A provider never exposes tools. To let an agent call a tool or query an API, use a connector. Because both go through one gateway, Aperture records model usage and tool usage in one place.

## Two protocols

Verified and custom connectors use one of two protocols to reach their upstream service:

* **MCP connectors**: Point at remote [Model Context Protocol][xt-mcp-spec] servers. Aperture combines their tools and resources behind the `/v1/mcp` endpoint. An agent finds and calls tools through Aperture. The agent does not need the address of the server that provides each tool.
* **HTTP connectors**: Make Aperture an authenticated reverse proxy. An agent sends a request to `/v1/connectors/<id>/<path>`. Aperture adds the connector's credentials and sends the request to the upstream API.

You can use both protocols in one configuration. MCP tools are available at `/v1/mcp`. HTTP APIs are available at their proxy paths.

### Name prefixing

Aperture adds the connector ID to the front of each name that it exposes to agents. This prevents a conflict when two servers have a tool with the same name:

* Tools get the ID and an underscore, such as `docs_search`.
* Resources and resource templates get the ID and a hyphen, such as `docs-files://readme.md`.

Aperture removes the prefix before it sends a call to the upstream. Because the underscore and the hyphen are separators, connector IDs can contain only letters and digits.

### HTTP connector discovery

If at least one HTTP connector exists, the `aperture` system connector also provides the `aperture_list_connectors` tool. This tool lists the HTTP connectors that the user has a `proxy` grant for. Users get the tool through a grant on the `aperture` system connector.

## The authentication model

Verified and custom connectors keep credentials in one place. You store API keys and tokens in the Aperture configuration, not in each agent. Aperture adds the correct credential to each outbound request. To rotate a credential, you change it in one place.

These connectors support static bearer tokens, API keys, HTTP basic authentication, and three OAuth 2.0 types: client credentials, authorization code, and dynamic client registration. The most important difference is between shared and per-user credentials:

* **Shared credentials**: Static tokens, API keys, basic authentication, and OAuth 2.0 client credentials authenticate Aperture to the upstream. All users with a matching grant use the same credential. Give these credentials the smallest scope possible, ideally read-only.
* **Per-user credentials**: OAuth 2.0 authorization code and dynamic client registration require each user to give consent. Aperture keeps a separate session and separate tokens for each user. Users' sessions do not mix, even on upstream servers that store state for each token.

A per-user connector shows a user no tools until that user authorizes it. After consent, Aperture runs tool discovery. Tool discovery requests the connector's tool list from the upstream with the user's credentials. Then it returns the user to the page where they started. If discovery fails or takes more than a few seconds, the tools might not appear immediately. A later request can find them, or the user can select **Refresh tools** on the connector's detail page in the [Aperture Chat portal][docs-aperture-chat-connectors].

Built-in connectors handle authentication differently:

* The [`Tailnet` connector][docs-connectors-built-in] needs a Tailscale OAuth client secret. It uses the OAuth 2.0 authorization code type, but a grant is enough to use its tool.
* The `Tailnet` connector does not use the **Connect** button. Each tool call starts authorization when it is necessary. For details, refer to its [authorization flow][docs-connectors-built-in-auth-flow].
* The `TailnetSSH` connector uses the Tailscale identity of the gateway. It needs no connector credential.

For authentication types, fields, callbacks, and token lifecycle, refer to [connector authentication][docs-connector-authentication].

## Capability discovery and updates

Aperture shows each user the MCP tools, resources, and templates that their connectors make available to them. How Aperture keeps that list current depends on the connector.

For an MCP connector with shared credentials, Aperture polls the upstream every few seconds. Aperture does not poll a connector that sets `send_caller_identity`. The result of a poll depends on the upstream:

* **The poll succeeds**: Aperture updates the tools and resources to match the upstream.
* **Aperture cannot reach the upstream**: Aperture removes the connector's tools from `/v1/mcp` until a later poll succeeds. The connector's resources and resource templates stay in the list. Aperture Chat can still show the last cached tool list.
* **Aperture reaches the upstream, but a list request fails**: Aperture keeps the capabilities that it already has.

Aperture does not poll per-user OAuth connectors. Instead, it discovers and caches a separate tool list for each user, with that user's credentials. Discovery runs after consent, and again on a later request after the cached list expires. One user's tool list does not affect another user's tools.

A connector's detail page shows cached capabilities and does not contact the upstream. To get upstream changes immediately, select **Refresh tools** on the connector's detail page in the Aperture Chat portal. Discovery and refresh contact the upstream, so they fail if the upstream is unreachable. Neither requires an Aperture restart.

Tools from the `aperture` system connector and built-in connectors run inside Aperture. Their tools change only with Aperture releases.

A listed tool does not prove that a call to it succeeds. A connector can show the [**Ready** status][docs-connectors-reference-statuses] while an upstream request or a refresh fails, because **Ready** describes access and authorization, not upstream health.

## Access control

Aperture denies connector access by default, as it does for the rest of the gateway. A user without a matching grant gets no connector capabilities.

Grants use `"connectorID/category/resource"` glob patterns. The category is `tools`, `resources`, `templates`, or `proxy`. Aperture checks grants when a client lists capabilities and again when the client uses one. A user can list and call only what their grants permit.

The `aperture` system connector gets no special treatment. Grants control it like any other connector. This is why the default configuration includes a grant for its tools.

The `proxy` category controls the raw proxy path `/v1/connectors/<id>/...`. MCP connectors are also reachable at this path. On this path, Aperture checks only the connector's `proxy` grant. It does not apply the per-tool and per-resource checks that it applies on `/v1/mcp`.

### Labels group connectors for grants

A pattern such as `docs/tools/*` names one connector. If your grants use only this kind of pattern, you add a grant entry for each new connector. With labels, you do not need a grant entry for each connector. A label is a string on a connector. A grant pattern of `label:<name>` matches every connector with that label. For example, label a set of connectors `sales` and grant `label:sales` one time. A connector that you add to the set later is covered without a grant change.

Aperture applies two rules to labels:

* **Matching is exact**: Labels do not support globs, the same as `tag:` and `group:` in Tailscale grants. The pattern `label:team.*` matches nothing.
* **A label grants the whole connector**: A matching label grants every category and resource of the connector. To grant a single tool, use a pattern with the connector ID.

A new Aperture gateway already uses a label. The [`aperture` system connector][docs-system-connectors] has the `system` label, and the default configuration grants `label:system`. This gives you a working example of label-based access. If you override the labels of the `aperture` system connector with `connectors.system_labels`, include `system`. If you do not, the default grant no longer covers its tools.

The [`Tailnet` and `TailnetSSH` connectors][docs-connectors-built-in] cannot have the `system` label. Aperture removes the reserved `system` label from every `connectors.servers` entry. Grant these connectors by ID or by a label that you assign. Admins manage connector labels under **Administration** > **Connectors** in the Aperture admin dashboard. Aperture Chat does not show labels.

Labels can only add access. Grants are additive and allow-only, so a label never removes access. A label such as `restricted` does not restrict anything by itself. A user with a broad `"**"` grant can still use a connector labeled `restricted`.

To restrict access, use narrow grants. For label syntax and the reserved `system` label, refer to [connector labels][docs-connectors-reference-labels]. For the procedure, refer to [grant connector access by label][docs-grant-connector-access-by-label].

## How HTTP connectors limit credential exposure

An HTTP connector sends client requests to an upstream with credentials added. To reduce the risk that these credentials leak, Aperture limits the proxy:

* It removes the client's `Authorization`, `Cookie`, and `Tailscale-*` headers, then adds the connector's credentials.
* It removes `Set-Cookie` headers from upstream responses.
* It blocks all upstream redirects, so a redirect cannot send the credentials to another server.
* It accepts only `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, and `OPTIONS`. It rejects methods such as `TRACE`, which can return the added credentials to the client.

As a result, an HTTP connector is a narrow gateway that adds credentials, not a general-purpose proxy. Your agreement with the upstream service controls how that service handles the requests.

These limits affect the errors that you get:

* **502 Bad Gateway**: The upstream is unreachable, the upstream responded with a redirect, or a per-user connector has no token for the caller.
* **405 Method Not Allowed**: The request uses a method that Aperture does not accept.
* **404 Not Found**: The caller has no `proxy` grant. An admin, or a caller with another grant on the connector, gets a 403 instead.

Aperture cuts off any response larger than 50 MB and does not return an error. If a response is incomplete, the full response might be larger than this limit.

## Related

For more information, refer to these topics:

* [Use a connector][docs-connectors-use]: Authorize a connector, call its tools, or query its API.
* [Get started with connectors][docs-connectors-get-started]: Add a connector and grant access as an admin.
* [Kinds of connector][docs-connectors-kinds]: Compare the connectors that Aperture runs with the connectors that send calls to an upstream.
* [Grant connector access by label][docs-grant-connector-access-by-label]: Group connectors and grant access to the group.
* [Connectors reference][docs-connectors-reference]: Find configuration fields and validation rules.
* [Connector authentication][docs-connector-authentication]: Find authentication types and authorization behavior.

[docs-aperture-chat-connectors]: /docs/aperture/reference/chat#connectors

[docs-aperture-set-up-providers]: /docs/aperture/set-up-providers

[docs-connector-authentication]: /docs/aperture/connectors/authentication

[docs-connectors-built-in]: /docs/aperture/connectors/built-in-connectors

[docs-connectors-built-in-auth-flow]: /docs/aperture/connectors/built-in-connectors#authorization-flow

[docs-connectors-get-started]: /docs/aperture/connectors/get-started

[docs-connectors-kinds]: /docs/aperture/connectors/kinds-of-connector

[docs-connectors-reference]: /docs/aperture/connectors/reference

[docs-connectors-reference-labels]: /docs/aperture/connectors/reference#connector-labels

[docs-connectors-reference-statuses]: /docs/aperture/connectors/reference#connector-statuses

[docs-connectors-use]: /docs/aperture/connectors/use-a-connector

[docs-grant-connector-access-by-label]: /docs/aperture/how-to/grant-connector-access-by-label

[docs-system-connectors]: /docs/aperture/connectors/system-connectors

[xt-mcp-spec]: https://modelcontextprotocol.io/specification
