Join us June 23 to see the ROI of switching to Tailscale.REGISTER ->

Use a connector

Last validated:

Aperture connectors are currently in alpha.

Aperture connectors are in public alpha. The connectors grant syntax and the connectors configuration section may change. The mcp_tools, mcp_resources, and mcp_templates grant fields are deprecated. Use the connectors field instead.

This guide is for users whose agents call tools and query APIs through connectors that an admin has already configured. To configure connectors yourself, refer to get started with connectors instead.

Prerequisites

An admin has configured the connector and granted you access. If a connector shows a No access status, ask your admin to add a grant for you.

Check a connector's status

Open the Connectors page in the Aperture dashboard. Each connector shows a status icon. Hover over it to view the status. The status tells you what to do next:

StatusWhat it meansWhat to do
ReadyAuthorized and accessible.Call its tools or query its API.
Needs authYou have access but have not authorized yet. A warning icon marks the connector.Authorize the connector (next section).
MisconfiguredThe OAuth token lacks a refresh token.Ask your admin to enable offline access for the connector. After your admin enables it, select the connector and choose Reconnect.
No accessYou have no matching grant.Ask your admin to grant you access.

Authorize a per-user connector

Connectors that use the OAuth 2.0 authorization code flow require each user to authorize individually.

  1. Open the Connectors page, select the connector, and choose Connect. The Aperture API equivalent is POST /api/connectors/<id>/connect, which returns {"auth_url": "..."}.
  2. Open the authorization URL in a browser and grant consent.
  3. Aperture redirects you back and shows a success page. The connector's tools then appear in your tool list.

Authorization expires after 15 minutes if you do not complete it.

Discover and call tools

Once a connector is Ready, your agent reaches its capabilities through Aperture. You can list and call only the tools your grants permit.

Send these requests from a device on your tailnet. Aperture identifies you from the Tailscale connection, so no API token is required.

  • MCP tools in chat or agent clients: When a connector is Ready, its tools appear automatically and your agent calls them. You do not need to list them yourself.

  • MCP tools in a custom MCP client: Point your MCP client at the Aperture /v1/mcp endpoint and list tools. Aperture prefixes each tool with its connector ID and an underscore. For example, a search tool from a connector with ID github is exposed as github_search.

    curl http://<aperture-hostname>/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

  • HTTP APIs: Send requests to /v1/connectors/<id>/<path>. Aperture injects the connector's credentials automatically. To find the available HTTP connectors, call the built-in aperture_list_connectors tool.

    curl http://<aperture-hostname>/v1/connectors/github/user

Reconnect when tools stop working

If a per-user OAuth connector still shows Ready but its tools stop working after a period of inactivity, its stored token is broken: the refresh token has expired or been revoked. To recover:

  1. Open the Connectors page and select the connector.
  2. Choose Disconnect, then Connect to re-authorize.

Disconnecting and reconnecting is safe. It forces Aperture to generate fresh tokens, which also clears a token that is broken but still present.