# Use a connector

Last validated Jun 15, 2026

> **Note:** Aperture connectors are currently in alpha.

\[Missing snippet: aperture\_mcp\_experimental\_note.mdx]

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][kb-connectors-get-started] 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][kb-grant-model-access] 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:

| Status        | What it means                                                                    | What to do                                                                                                                             |
| ------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Ready         | Authorized and accessible.                                                       | Call its tools or query its API.                                                                                                       |
| Needs auth    | You have access but have not authorized yet. A warning icon marks the connector. | Authorize the connector (next section).                                                                                                |
| Misconfigured | The 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 access     | You 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`.

  ```shell
  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.

  ```shell
  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.

## Related

* [Get started with connectors][kb-connectors-get-started] - Configure a connector and grant access.
* [How connectors work][kb-connectors-how-it-works] - Understand the connector model, authentication, and access control.
* [Connectors reference][kb-connectors-reference] - Connector statuses, authentication types, and protocol behavior.
* [Control model access][kb-grant-model-access] - Grant users access to connectors and tools.

[kb-connectors-get-started]: /docs/aperture/connectors/get-started

[kb-connectors-how-it-works]: /docs/aperture/connectors/how-connectors-work

[kb-connectors-reference]: /docs/aperture/connectors/reference

[kb-grant-model-access]: /docs/aperture/how-to/grant-model-access