See everything you missed at TailscaleUp.Read the recap →

Use a connector

Last validated:

Use connectors that your administrator has configured to let agents call tools and query APIs. To configure connectors yourself, refer to Get started with connectors.

Prerequisites

An admin has configured the connector and granted you access. Aperture omits configured connectors that your grants deny. Opening a denied connector's detail URL shows the same not-found state as a connector that does not exist, so ask your admin to check your grant if an expected connector is missing.

Check a connector's status

Open Connectors in the Aperture Chat portal.

Section or statusMeaningAction
Ready to use and ReadyYou have access and any required authorization. This does not test upstream health.Select the connector to review its tools.
Connect to use with ConnectYou have access but have not authorized this per-user connector.Select Connect and complete consent.
Needs reconnect with ReconnectThe saved authorization is no longer usable.Correct the OAuth configuration if needed, then select Reconnect.
Temporarily unavailableAperture could not read your credential state.Reload the page and try again.

Aperture does not show No access in Chat. It omits connectors that your grants deny.

Authorize a per-user connector

  1. Open Chat Connectors.
  2. Under Connect to use, select Connect.
  3. Sign in to the provider and grant consent.
  4. Return to the connector detail page and confirm Ready.

A pending authorization expires after 15 minutes.

Review or refresh MCP tools

Select a Ready MCP connector to review its Tools. The detail page groups tools under Interactive tools, Read-only tools, and Write/Delete tools when present. Select Refresh tools to contact the upstream service and request its current tools. A failed refresh reports Couldn't refresh tools. without changing Ready, because status describes access and authorization rather than upstream health.

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 in 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" \
  -H "Accept: application/json, text/event-stream" \
  -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 Chat Connectors 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.