See everything you missed at TailscaleUp.Read the recap →

Get started with connectors

Last validated:

Add your first Aperture connector, grant access to its capabilities, and verify the connection from a client. For background on how connectors work, refer to How connectors work. For complete field definitions, refer to the connectors reference.

Prerequisites

Before you begin, you need the following:

  • Aperture enabled on your tailnet. Refer to Get started with Aperture if you have not set this up.
  • Admin access to the Aperture configuration. This topic explains how to edit the connectors and grants sections.
  • The URL of at least one upstream service such as an MCP server or HTTP API, reachable from the Aperture host.

Step 1: Add a connector

Connectors that use oauth2_authorization_code or oauth2_client_credentials require an upstream OAuth application. Authorization-code clients can use PKCE without a client secret, while client-credentials connectors require a client secret. On the MCP server or API provider:

  • For either method, create the OAuth application and note the client ID and token URL. For client credentials, also note the required client secret. For authorization code, note the client secret only if the application uses one.
  • For oauth2_authorization_code, register Aperture's callback URL (https://<aperture-hostname>/aperture/auth/<connector-id>/callback) and note the authorization URL and user authorization scopes.

Connectors live in the connectors section of the Aperture configuration.

Open the Aperture dashboard and go to Administration > Connectors.

That page is the visual editor and holds the connector picker. To edit the connectors section as JSON instead, use the Administration > Configuration page.

You can add connectors in two ways:

  • From the verified registry: The connector picker includes pre-configured defaults for common providers such as Salesforce, Atlassian, Slack, GitHub, Notion, and Linear. Open the picker for the current list. Selecting a provider pre-fills its configuration. Some require OAuth client credentials, but connectors using oauth2_dcr, including Atlassian, Notion, and Linear, do not because Aperture registers the OAuth client automatically. For more information, refer to Add a verified connector.
  • Custom configuration: Add a connectors section with one or more server entries. Each entry needs a protocol ("mcp" or "http") and a url.

The following example adds an unauthenticated MCP server and an authenticated HTTP API:

{
  "connectors": {
    "servers": {
      "docs": {
        "protocol": "mcp",
        "url": "http://mcp-server.example.ts.net:8185/v1/mcp"
      },
      "github": {
        "protocol": "http",
        "url": "https://api.github.com",
        "description": "GitHub REST API (read-only)",
        "auth": {
          "type": "bearer_token",
          "secret": "github_pat_example"
        }
      }
    }
  }
}

Each key in the servers map is a connector ID that Aperture uses as a name prefix. Connector IDs must contain only letters and digits, starting with a letter. The IDs tailscale, internal, and aperture are reserved. Refer to the connectors reference for the full ID rules and authentication types.

Aperture supports bearer_token, api_key, basic, oauth2_client_credentials, oauth2_authorization_code, and oauth2_dcr authentication. Refer to the connectors reference for each type's fields.

The Aperture host uses its tailnet HTTP client for connections, so you can use MagicDNS hostnames (for example, http://mcp-server.example.ts.net:8080/v1/mcp) without additional network configuration.

Step 2: Grant access

Aperture denies connector access unless a grant matches the request. Add grants in the grants section of your configuration.

Open the Aperture dashboard and go to Administration > Grants.

Use the visual grant editor, or edit the same grants as JSON on the Administration > Configuration page.

To change the configuration programmatically, refer to the grants configuration reference.

The following example grants every capability from every connector, including Aperture's built-in tools:

{
  "grants": [
    {
      "src": ["*"],
      "app": {
        "tailscale.com/cap/aperture": [
          {"connectors": ["**"]}
        ]
      }
    }
  ]
}

Connector grants use the connectors field with "connectorID/category/resource" glob patterns. The valid categories are tools, resources, templates, and proxy. Both MCP and HTTP connectors require grants. Refer to the grants configuration reference for the full syntax.

A "**" grant reaches every connector you add later, including sensitive ones. Use it only while you verify your first connector.

Labels are another way to write a connector grant. A label is a flat string you set on a connector, and one label:<name> pattern grants every connector carrying that label. Once you have more than one connector, replace the broad grant with labeled groups. Refer to Grant connector access by label.

Step 3: Verify the connection

Verify the connector in the dashboard first, then verify access from a client.

Check the connector status

  1. Open the Connectors page in the dashboard.
  2. Select the connector.
  3. Confirm the status shows Ready.
  4. For an MCP connector, confirm the capability list contains the tools, resources, and resource templates you expect.

The page loads cached capabilities when available. For a Ready MCP connector, use Refresh to fetch current capabilities from the upstream service. Connection failures appear on the Connectors page.

Diagnose a connector that is not ready

If the connector does not show Ready, its status indicates the cause:

  • Needs auth: The connector uses per-user OAuth and the current user has not authorized it. Authorize the connector before calling it.
  • Misconfigured: Aperture stored an authorization without a refresh token. Reauthorize the connector and make sure the upstream OAuth application grants offline access.
  • No access: Your tailnet identity has no grant for this connector. Revisit Step 2.

If a capability refresh returns 502 upstream error, Aperture could not connect to the upstream MCP server. Confirm the url is correct and reachable from the Aperture host.

When you call a connector and receive a 403 access denied response, the caller's tailnet identity lacks a matching grant. Revisit Step 2.

Verify access from a client

Once the connector shows Ready, verify access from a client. Run these commands from a device on your tailnet whose identity has the grants from Step 2. Aperture authorizes each request from the caller's tailnet identity, and <aperture-hostname> is the Aperture host's MagicDNS name.

For MCP connectors, point your MCP client at the Aperture URL and list available tools:

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}'

The response contains a tools array with prefixed entries from your configured connectors (for example, docs_search).

For HTTP connectors, send a request through the Aperture proxy path:

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

Aperture forwards the request to https://api.github.com/user and injects the configured bearer token automatically.

Next steps