Last chance to meet us at TailscaleUp!Grab your ticket ->

Kinds of connector

Last validated:

Aperture tools come from different sources. Some ship with the gateway, some require configuration, and some forward calls to an upstream service. Two properties distinguish them: who runs the tool and who can reach it.

For field definitions, refer to the connectors reference. For the connector model, refer to How connectors work.

Execution and reachability

Each tool in Aperture falls on two axes:

  1. Execution: Aperture runs the tool itself, or Aperture forwards the call to an upstream service.
  2. Reachability: The tool is available to chat only, or to both chat and agents connected to the gateway.

Execution determines failure modes. A tool Aperture runs cannot fail because of a network partition or an expired upstream credential. A tool Aperture forwards is only as available as its upstream.

Reachability determines whether grants apply. Tools that agents can reach pass through the grant system. Chat-only capabilities do not.

Connector types

KindExecutionReachabilityRequires configurationGoverned by grants
Chat-only toolsApertureChatNoNo
The aperture connectorApertureChat and agentsNoYes
Built-in connectorsApertureChat and agentsYesYes
Verified connectorsUpstreamChat and agentsYesYes
Custom connectorsUpstreamChat and agentsYesYes

The last three require a configuration entry. The first two ship with the gateway.

Chat-only tools

The chat sandbox and location are capabilities of the chat interface rather than connectors. They have no entry in your configuration, no upstream URL, and no connector ID. An agent that connects to /v1/mcp never receives them in a tool listing, so no grant pattern reaches them or excludes them.

Four controls decide whether a chat-only capability is active, and a grant is not among them:

  • A feature flag Tailscale sets for your gateway.
  • A runtime dependency, such as a configured sandbox backend.
  • A per-conversation toggle the user sets.
  • A user policy or project policy an admin sets.

Location goes further than the sandbox: it registers no tool at all. Chat reads the user's coordinates from the request and places them in the system prompt, so the model has the information without any tool call.

For what the sandbox does, refer to the chat sandbox feature guide.

The aperture connector

The built-in aperture connector sits across the usual boundary. Aperture runs its tools, as it does for a chat-only capability, and the connector still appears in the connector listing, agents still receive its tools, and grants still govern it. It has no entry in your configuration because it ships with every gateway.

Its tools are aperture_list_connectors, which lets a model discover the HTTP connectors it can reach, and the web tools aperture_web_search and aperture_web_fetch. The web tools depend on a feature flag and a configured search backend. A gateway without them shows the connector with a shorter tool list rather than hiding the connector.

This connector carries the system label, and the shipped default configuration grants label:system. That grant is why the built-in tools work on a new gateway, and it gives you a working example of label-based access. The authorization path contains no exception for it.

Built-in connectors

A built-in connector runs inside Aperture as the aperture connector does, but it requires an entry in your configuration before it does anything. The tailnet connector provisions nodes on your tailnet, and the Tailscale SSH connector lists tailnet machines and runs commands on them.

These connectors have no upstream URL and nothing to proxy. Their tools are part of the Aperture binary.

  • Aperture never polls them for capability changes, because their tool list is fixed at build time. A new tool arrives in an Aperture release, not from a change you make.
  • The raw proxy path /v1/connectors/<id>/<path> returns a 404 for them, since there is no upstream to forward a request to.

Because they need configuration, a built-in connector is subject to grants and appears in the connector listing with a status, the same way a connector that points at an outside service does. Access control works the same for both. The source of the tools is what differs.

Verified connectors

A verified connector points at an outside service, and Aperture forwards each call to it. Its provider appears in Aperture's registry, which supplies a starting configuration: the protocol, the authentication type, the authorization and token endpoints, and the scopes.

The registry saves you from finding those values yourself, and does nothing at run time. Once an admin saves the connector, Aperture reads only the stored configuration, so a registry value that changes at the provider leaves your gateway alone.

Custom connectors

A custom connector is a verified connector without the preset. You supply the URL, the protocol, the authentication scheme, and the credentials. Aperture treats it identically at run time.

Custom does not mean an upstream on your own tailnet, despite the common assumption. The distinction is registry presence, and a custom connector can point at any address Aperture can reach. The send_caller_identity field does require a tailnet upstream. It forwards the caller's Tailscale identity to the upstream and is rejected unless the URL is a MagicDNS name or a Tailscale IP address.

Behavioral differences by type

Grants: A grant of "**" covers every tool from every connector, including built-in connectors, but not chat-only capabilities. Chat-only capabilities are absent from the grant namespace. To control the sandbox, use the feature flag and policies described in Chat-only tools.

Polling: Aperture polls each forwarding connector (verified and custom) every few seconds and updates the tool list when the upstream changes. Built-in connectors have a fixed tool list compiled into Aperture, so there is nothing to poll. Per-user connectors have no shared credential to poll with, so Aperture skips them.

Upstream failures: When a forwarding connector's upstream becomes unreachable, Aperture unregisters that connector's tools and re-registers them when the service recovers. Other connectors are unaffected. Tools Aperture runs itself cannot fail this way.

Credentials: Only forwarding connectors hold upstream credentials. Built-in connectors have no credential to rotate or scope. For credential configuration, refer to the connectors reference.

API categories

The connector listing in the API and admin console includes a category field with the value system, verified, or custom. These three values do not map one-to-one to the five connector types:

  • Chat-only capabilities are absent from the listing, so they have no category.
  • Built-in connectors are reported as system, together with the always-present aperture connector, even though they require configuration.
  • verified and custom match the kinds described above.

The category field is a display grouping for the admin console. To predict connector behavior, use the execution and reachability properties described in Connector types. For the field definition, refer to the connectors reference.

Examples

A colleague adds a tool to an MCP server on your tailnet. When can an agent call it? Aperture polls forwarding connectors, so the tool appears within seconds if a matching grant exists. A built-in connector tool, by contrast, arrives only in an Aperture release.

A user has a "**" grant but the chat sandbox is unavailable. Where do you look? The sandbox is chat-only. Grants do not apply. Check the feature flag, sandbox backend, conversation toggle, and project policy.

An upstream service returns errors for an hour. Which tools are affected? Only that connector's tools. Built-in connectors and the aperture connector continue working because they run inside the gateway.

You want Tailscale SSH available to one team only. What do you change? The grant. Built-in connectors have no URL or credential to scope, so access control is the only mechanism.