Get started with connectors

This guide walks you through enabling connectors, adding your first connector, granting access, and verifying the connection. 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. You edit the flags, connectors, and grants sections in this guide.
• The URL of at least one upstream service such as an MCP server or HTTP API, reachable from the Aperture host.

Step 1: Enable the feature flag

Open the Settings page of the Aperture dashboard and add the connectors feature flag to your configuration:

{
  "flags": {
    "connectors": {"value": true}
  }
}

Step 2: Add a connector

You can add connectors in two ways:

• From the verified registry: The dashboard connector picker includes pre-configured defaults for many common providers. For example, Salesforce, Atlassian, Slack, GitHub, Notion, and Linear. Open the picker in the dashboard for the current list. Select a provider, and Aperture pre-fills the URL, auth URLs, token URLs, and scopes. You supply only your OAuth client credentials.
• 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": {
      "local": {
        "protocol": "mcp",
        "url": "http://localhost: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, and oauth2_authorization_code authentication. Refer to the connectors reference for each type's fields.

Step 3: Grant access

Aperture is deny-by-default. Without grants, users cannot access any connector capabilities. Add grants in the grants section of your configuration.

The following example grants all users access to every connector capability, including the built-in Aperture 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.

Step 4: Verify the connection

First, verify the connector in Aperture. Open the Connectors page in the dashboard, select the connector, and confirm its status shows Ready and that the capability list contains the tools, resources, and templates you expect. The Connectors page probes the upstream URL, so a connector that cannot reach its server or list its capabilities surfaces the error here.

If the connector isn't Ready

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

• Needs auth: The connector uses OAuth and no one has authorized it yet. Authorize the connector before calling it.
• Misconfigured: A token is stored but cannot be refreshed. 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 3.

If the capability list fails to load, the Connectors page shows an upstream error (such as 502 upstream error). This means Aperture reached the connector but the upstream URL could not be reached or could not list its capabilities. 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 3.

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 3. Aperture authorizes each request from the caller's tailnet identity, and <aperture-hostname> is the Aperture host's tailnet (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" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

The response contains a tools array with prefixed entries from your configured connectors (for example, local_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

• Set up an HTTP API connector to proxy requests to an upstream REST API with automatic authentication.
• Set up a per-user OAuth 2.0 connector to connect agents to services that require individual user authorization.
• Use a connector once it is configured, to authorize and call its tools as an end-user.