Visit us at ReInvent How to find us →

How connectors work

Last validated:

Connectors let agents call tools and query APIs through Aperture. Connectors differ in where their tools run:

  • Built-in connectors run their tools inside Aperture.
  • Verified and custom connectors send calls to an upstream MCP server or HTTP API. Aperture can inject configured credentials into each call.

Connector grants control access to every kind. For more about each kind, refer to Kinds of connector. For field definitions, refer to the connectors reference.

Connectors and providers

Aperture routes two kinds of agent traffic:

  • Providers route LLM requests to upstream model APIs.
  • Connectors give agents access to tools and APIs. They forward requests to an upstream service or run a built-in tool inside Aperture.

A connector never serves model completions, and a provider never exposes tools. Together, they give Aperture visibility into model and tool usage through one gateway. To let an agent call a tool or query an API, use a connector.

Two protocols

Each verified or custom connector uses one of two protocols. The protocol sets how Aperture communicates with the upstream service and how agents reach the connector.

  • MCP connectors: Point at remote Model Context Protocol servers. Aperture aggregates their tools and resources behind the /v1/mcp endpoint. An agent discovers and calls tools through Aperture without knowing which backend serves each tool.
  • HTTP connectors: Turn Aperture into an authenticated reverse proxy. An agent sends a request to /v1/connectors/<id>/<path>, and Aperture forwards it to the upstream API with credentials injected automatically.

You can mix both protocols in one configuration. MCP tools surface through /v1/mcp, and HTTP APIs surface through their proxy paths. When at least one HTTP connector exists, Aperture also exposes a built-in tool that lets models discover the available HTTP connectors.

Name prefixing

Each connector ID becomes a name prefix, which prevents collisions when two servers expose a tool with the same name. Tools take the ID and an underscore (docs_search). Resources and resource templates take the ID and a hyphen (docs-files://readme.md). Aperture strips the prefix when it forwards a call to the upstream. This is why connector IDs allow only letters and digits: underscores and hyphens are reserved as separators in the prefixed names exposed to agents.

The authentication model

Verified and custom connectors centralize credentials. You store API keys and tokens in the Aperture configuration instead of giving them to every agent runtime. Aperture injects the correct credential on each outbound request, so you rotate a credential in one place.

These connectors support several authentication schemes, including static tokens, API keys, HTTP basic, and two OAuth 2.0 flows. Two credential models determine who authorizes access:

  • Shared credentials authenticate every permitted request with the same token, API key, basic credentials, or OAuth 2.0 client credentials. Scope them narrowly, preferably read-only.
  • Per-user authorization requires each user to consent through OAuth, including dynamic client registration. Aperture stores each user's tokens separately and isolates their MCP sessions.

Per-user connectors do not expose tools to a user until that user completes OAuth authorization. Both models require matching connector grants. For how Aperture discovers tools after authorization, refer to Capability discovery and updates. For the complete authentication-type catalog, callbacks, and token lifecycle, refer to Connector authentication.

Some tools ask a user to authorize a specific action when an agent calls them, instead of requiring authorization for the whole connector up front. The built-in Tailnet connector works this way. It uses the OAuth 2.0 authorization code type, but its tool is available with a grant alone, and the Connect button does not apply. The first call returns an authorization link, and a call after the user approves returns the result. Refer to its authorization flow. For authentication requirements, scheme-specific fields, and provider-specific configuration parameters, refer to the connectors reference and Connector authentication.

Capability discovery and updates

Aperture shows each user the MCP tools, resources, and templates that their grants permit.

For a verified or custom MCP connector without per-user credentials, Aperture polls the upstream every few seconds. When the upstream adds or removes a tool, Aperture updates the registered capabilities. If the upstream becomes unreachable, Aperture removes its tools from /v1/mcp until the upstream recovers. Aperture Chat can still show the last cached tool list. A listed tool does not guarantee that a live call succeeds.

Built-in connector tools run inside Aperture, so Aperture does not poll them.

Per-user OAuth connectors do not use background polling. Aperture discovers and caches a separate tool catalog for each user with that user's credentials:

  • After consent, Aperture tries to discover tools before it redirects the user to Aperture Chat. If the upstream is slow or unreachable, the tools might not appear immediately.
  • If that first discovery does not complete, a later request from the user can discover the tools.
  • One user's catalog does not populate another user's tools.

A connector's detail page shows cached capabilities and does not contact the upstream. To get upstream tool changes, open the connector's detail page under Connectors in the Aperture Chat portal and select Refresh tools. Discovery and refresh contact the upstream, so either can fail if the upstream is unreachable. A failed refresh reports an upstream error but does not change Ready. Connector status describes access and authorization, not upstream health. Neither discovery nor refresh requires an Aperture restart.

Access control

Aperture is deny-by-default for connectors, the same as for the rest of the gateway. Without a matching grant, a user sees no connector capabilities. Grants use "connectorID/category/resource" glob patterns, where the category is tools, resources, templates, or proxy. Aperture checks grants both when a client lists capabilities and when it invokes one, so a user can list and call only what their grants permit. The aperture system connector has no special authorization bypass. Grants govern its tools like any other connector. The shipped default configuration grants access to those tools rather than relying on an exception in the code.

The proxy category governs the raw proxy path /v1/connectors/<id>/.... An MCP connector is also reachable through that path, and on it Aperture applies only the connector-level proxy grant, not the per-tool and per-resource filtering it applies on /v1/mcp.

Labels group connectors for grants

An FQN pattern names one connector, so a policy expressed only in FQN patterns grows by one entry for every connector you add. Labels solve that. A label is a flat string on a connector, and a grant pattern of label:<name> matches every connector with that label. Label a set of connectors sales, grant label:sales once, and a connector added to that set later is covered without a policy change.

Two rules follow from how Aperture evaluates a label. Matching is exact rather than glob-based, the same as tag: and group: in Tailscale grants, so label:team.* matches nothing. And a matching label grants the whole connector at every category and resource, so labels express connector-level policy while FQN patterns remain the way to reach a single tool.

Labels are also where a new Aperture gateway starts. The aperture system connector has the system label by default. The shipped default configuration grants label:system, so the configuration includes a working label-based access example. You can grant access to the built-in Tailnet and TailnetSSH connectors by connector ID or by a label you assign. Admins manage and review connector labels under Administration > Connectors. The personal Chat portal does not list connector labels.

Labels can only widen access. Grants are additive and allow-only, so a label adds the connectors it matches to a user's access and never subtracts anything. A sensitivity label such as restricted records intent but enforces nothing on its own: a user with a broad "**" grant still reaches a connector labeled restricted. Use narrow grants to restrict access. For the label grammar and the reserved system label, refer to the connectors reference, and for the task itself, refer to Grant connector access by label.

How HTTP connectors limit credential exposure

Because an HTTP connector forwards arbitrary client requests to an upstream with injected credentials, Aperture constrains the proxy to reduce the risk of credential leakage:

  • It strips client-supplied Authorization, Cookie, and all Tailscale-* headers before forwarding, then injects credentials based on the connector's auth configuration.
  • It strips Set-Cookie headers from upstream responses.
  • It blocks all upstream redirects, which reduces the risk of credential exfiltration through redirect chains.
  • It accepts only standard request methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS), rejecting methods such as TRACE that would echo the injected credentials back to the client.

These rules mean an HTTP connector behaves like a narrow, credential-injecting gateway rather than a general-purpose proxy. The upstream service's handling of forwarded requests is governed by your agreement with that service.

This shapes how failures surface. When an upstream is unreachable or errors at the connection level, Aperture returns 502 Bad Gateway. A request that uses a disallowed method returns 405 Method Not Allowed. Large responses are capped at a size limit and truncated, so a response that gets cut off may have exceeded that limit.