How connectors work

Last validated:

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. For fields and values, refer to the connectors reference.

Connectors and providers

Aperture handles two kinds of agent traffic:

  • 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 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.

Built-in connectors handle authentication differently:

  • The Tailnet connector 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.
  • 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.

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 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 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 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. For the procedure, refer to 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.

For more information, refer to these topics: