Manage connectors

A connector is an MCP server available through the Connector Gateway. Manage connectors in the console under Connectors. The list shows each connector's Name, Status, Endpoint, Transport, Groups with access, and Created date. Search by name or description, or filter by Status. Each row's actions menu opens the connector's Details, its Access tab, Configure, or Delete.

To make a connector available to users, add it, set up its authentication, confirm it passes its setup check, and grant access to at least one directory group. The setup wizard walks you through all four.

Add a connector

Select Add connector to open the setup wizard, or Import connector to start the wizard from a server your registry publishes or your cluster runs. The wizard has four steps:

1. Add connector: enter a Name, an optional Description, and the MCP server URL. Under Advanced options, choose the Transport, add Request headers, or turn on Allow private IPs for an in-cluster endpoint. Select Next.
2. Authentication: set how the gateway authenticates to the server. This step's title and fields depend on what the console finds out about the server; see Authentication in the wizard.
3. Grant access: choose the directory groups that can use the connector under Groups, then select Next. With no group chosen, the button reads Skip, and you grant access later from the connector's Access tab.
4. Connector added: leaving Grant access creates the connector, publishes it, runs its setup check, and grants the groups access. The step shows Your connector is ready, or Setup check failed with a link to Configure. Select Done.

The Connector Gateway serves connectors that use the streamable-http or sse transport. SSE is a deprecated MCP transport, so keep Streamable HTTP unless the backend supports only SSE.

Request headers are stored as plain text and sent with every request to the server. Put credentials in the connector's authentication instead.

Authentication in the wizard

For a public HTTPS URL, Next on the Add connector step checks the server's OAuth metadata, and the authentication step opens on one of three paths, each titled for what it asks:

• Choose an identity provider: the server's authorization server matches connector identity providers you already registered. Select the one the connector signs users in through, or select Create new provider.
• Set up an identity provider: the server uses OAuth and no existing provider matches. The wizard drafts a new connector identity provider from the server's metadata. If the authorization server supports dynamic client registration (DCR), the gateway registers its own client. Otherwise, enter the Client ID and Client secret of a client you registered with it. The wizard creates the provider when you finish, and the connector signs users in through it.
• Set up authorization: the console couldn't reach the server, couldn't determine the method, or the server didn't ask for authentication. A notice says which, and you choose the Authorization method yourself. See Configure connector authentication.

For a plain HTTP URL, a private or in-cluster address, or a server imported from Kubernetes, the wizard skips the check and opens Set up authorization.

Import a connector

Import starts the wizard prefilled from a server you pick.

1. Select Import connector, then Import from registry or Import from Kubernetes.
   • Import from registry lists the remote servers that your curated MCP registries publish. Choose a Registry, then the server. Container-only servers don't appear.
   • Import from Kubernetes scans your cluster for running MCP servers.
2. Select one server, then Next. A server that already has a connector shows Added and can't be selected.
3. Review the prefilled Name, Description, MCP server URL, and Advanced options. If the source doesn't report the server's transport, choose one under Advanced options.
4. Continue through the wizard as for any other connector.

An import from Kubernetes turns on Allow private IPs for a server whose endpoint is a Service in the server's own namespace. See Connect to in-cluster endpoints.

Check setup and publish a connector

The setup check confirms that the connector's identity provider, if it has one, is active and that the Enterprise Manager can open a connection to the endpoint. The result sets the connector's Status:

Status	Meaning
Draft	Created as a draft and not yet saved. The gateway withholds it.
Checking setup	The setup check is running.
Ready	The setup check passed. The gateway serves the connector.
Setup check failed	The setup check failed. The gateway withholds it.

Connectors that you add or import in the console are published on create. Drafts come from the Enterprise Manager API, and a draft's details page shows a Setup required banner.

To publish a draft, or to retry a connector whose setup check failed:

1. Open the connector and select Configure, or choose Configure from its row's actions menu.
2. Review the endpoint, transport, and authentication settings, and fix anything that caused a failure.
3. Select Save.

Saving publishes the connector and runs the setup check again. A Ready connector is checked again when you change its endpoint, authentication, or Allow private IPs setting. The check runs only when you save, so a connector stays Ready if its backend later goes down. If calls start failing, check the backend itself.

The console doesn't show why the setup check failed. See A connector shows Setup check failed to find the error.

Connect to in-cluster endpoints

By default, a connector endpoint must use HTTPS (plain HTTP is allowed only for localhost), and the gateway refuses to connect to an address in a private, loopback, or link-local range. An endpoint that points at a Kubernetes Service resolves to a private address, so it needs two settings:

1. Turn on Allow private IPs under the wizard's Advanced options (allow_private_ips in the API), or select Configure on an existing connector. The setting also permits plain HTTP. An import from Kubernetes turns it on for you when the endpoint is a Service in the server's own namespace.

2. Add the endpoint's address range to the allowlist of the Enterprise Manager's setup check. The setup check applies its own private-range check, independent of Allow private IPs. Add the narrowest range that covers your in-cluster MCP servers, such as your cluster's Service CIDR:

   values.yaml

   enterprise-manager:
     directory:
       connectorVerification:
         allowedPrivateRanges:
           - '<SERVICE_CIDR>'

Find the actual Service CIDR in the target cluster before replacing <SERVICE_CIDR>. In clusters that expose ServiceCIDR resources, list every configured range:

kubectl get servicecidrs -o json | jq -r '.items[].spec.cidrs[]'

If that resource is unavailable or your account cannot read it, get the Service ranges from your managed Kubernetes provider's cluster networking configuration or your cluster administrator. For a self-managed control plane, the API server's --service-cluster-ip-range setting identifies them. Use the Service ranges containing the discovered endpoints, including IPv6 ranges for a dual-stack cluster. Pod CIDRs describe a different address pool.

Apply the changed values with a Helm upgrade, then open each failed connector, select Configure, and select Save. A Helm upgrade updates the allowlist; persisted connectors are checked again only when you save them. Confirm Ready in the list before granting access to directory groups.

To check connector status through the API, use the Enterprise Manager API port-forward in a separate terminal, then list the connectors with an administrator access token:

curl --fail --silent --show-error \
  http://localhost:8080/v1/gateways/<GATEWAY_ID>/connectors \
  -H 'Authorization: Bearer <ADMIN_ACCESS_TOKEN>' \
  | jq '.items[] | {id, name, endpoint, status}'

available corresponds to Ready, and failure to Setup check failed. A successful create response alone does not establish availability. For failure, check the Enterprise Manager logs as described in A connector shows Setup check failed, fix the cause, and save again. Only available connectors enter the served catalog; their connector policies still determine who can use them.

The gateway never connects to link-local addresses such as the cloud metadata endpoint, even with Allow private IPs on. The Enterprise Manager refuses to start with a link-local or cloud metadata range in the allowlist. Leave loopback ranges out too, since they reach the Enterprise Manager pod's own listeners.

Set up authentication

A connector's authentication type sets the credential the gateway sends to its backend: none, a static secret, or a credential derived from the calling user's identity, such as their own OAuth token. Set it on the wizard's authentication step, or select Configure on an existing connector and save to run the setup check again.

Some types reference a managed secret or a connector identity provider. The wizard can create both as you go: New secret next to a secret picker creates a managed secret, and Set up an identity provider creates a provider from the server's OAuth metadata. See Configure connector authentication for each type and the order to create its prerequisites.

Grant and revoke access

Access is default-deny: a connector with no groups is unreachable. Grant directory groups access on the connector's Access tab, and revoke a group from its actions menu. See Grant and revoke connector access for the steps.

Review activity

A connector's Activity tab lists its recent allowed tool calls, with the Tool, User, and Time of each one.

• Choose the period: the last 24 hours, 7 days, or 30 days, or a Custom range.
• Select a user to show only that user's calls, and Clear user filter to return to everyone's.

The Activity tab is a best-effort view, not an audit log: calls can be delayed, sampled, or missing, and calls the connector policy refuses don't appear. For a complete per-request record, including refused calls, see Forward audit logs. The tab reads the same records as the Tool Usage screen, so it stays empty until you turn on tool call recording.

Edit or delete a connector

To edit a connector, open it and select Configure, or choose Configure from its row's actions menu. The wizard opens with the connector's current settings. Change what you need, select Next to reach Set up authorization, and select Save. A stored secret is kept unless you choose a new one. Changes to the endpoint, authentication, or Allow private IPs setting run the setup check again. A connector whose authentication type the console doesn't support opens read-only; edit it through the Enterprise Manager API.

To delete a connector, select Delete on its details page or from its row's actions menu, and confirm. Deleting is permanent and revokes every group's access to the connector.

When changes take effect

Each kind of change reaches users on a different schedule:

• Access changes apply on the user's next request. The gateway checks access with the Enterprise Manager on every request, and denies the request if it can't reach the Enterprise Manager.
• New and edited connectors reach the gateway within about 30 seconds, when it next refreshes its connector catalog.
• Rotated credentials in a managed secret reach the gateway within the credential refresh interval, 15 minutes by default. Set it with connector-gateway.enterpriseConfig.directory.credentialRefreshInterval in your Helm values.

Most MCP clients keep the tool list from when they connected, so a user might need to refresh their client's tool list to see a change. See When changes take effect for the user's side.

Next steps

• Register a connector identity provider for connectors that act as each user.
• Create managed secrets for connectors that use a static credential.
• Roll out gateway clients to connect your users' MCP clients to the gateway.

Troubleshooting

A connector shows Setup check failed

The console doesn't display the setup check's error. Find the failed write in the Enterprise Manager's logs, on a connector write persisted as failure line with the connector's ID and endpoint. When present, the err field gives the underlying cause:

kubectl logs deployment/stacklok-enterprise-enterprise-manager -n stacklok-system \
  | grep 'connector write persisted as failure'

Common causes:

• The endpoint is unreachable from the Enterprise Manager pod. Check the URL, DNS, and any egress NetworkPolicy or proxy between the Enterprise Manager and the backend.
• The endpoint is in-cluster. Check that its address falls within the setup check's allowlist, even when Allow private IPs is on. See the next entry.
• The connector's identity provider isn't active. Check the provider on the Identity providers screen.

After you fix the cause, open the connector, select Configure, and select Save. The connector keeps Setup check failed until it's saved again.

An in-cluster or internal endpoint is refused

An endpoint that resolves to a private, loopback, or reserved address passes two separate checks, and each has its own setting:

• If the wizard reports that the URL uses plain HTTP or is a private, loopback, or in-cluster address, or that "This endpoint resolves to a disallowed (private or reserved) IP range", turn on Allow private IPs under Advanced options.
• If the connector saves but shows Setup check failed, check that its address range is included in enterprise-manager.directory.connectorVerification.allowedPrivateRanges. A detailed log error, when available, reads resolves to a disallowed IP range.

An in-cluster endpoint needs both settings. See Connect to in-cluster endpoints.

If saving fails with "Could not resolve this endpoint's hostname", the Enterprise Manager can't resolve the host at all. Check the hostname and the Enterprise Manager pod's DNS.

A ready connector doesn't reach any users

The gateway refreshes its connector catalog from the Enterprise Manager every 30 seconds and withholds any connector it can't serve. Search the gateway's logs for the connector:

kubectl logs deployment/stacklok-enterprise-connector-gateway -n stacklok-system \
  | grep 'connector withheld from the served generation'

Each line names the connector and gives a reason, plus a remedy for most reasons. The most common are unresolved_credential, where the managed secret the connector references can't be read, and dangling_provider_reference, where the connector's identity provider failed to load. Fix the secret or provider; the gateway picks up the change on its next refresh.

A user can't see a connector

A user's MCP clients get a connector's tools only when all of these hold:

1. The connector is Ready.
2. The connector policy grants the user access. In structured mode, the user must belong to a granted group or one of its subgroups. A connector with no grants is unreachable. See Grant and revoke connector access.
3. The user has connected to the connector and hasn't paused it. See Support users' connector access.

For a Cedar-mode connector, a policy that reads a token claim the caller's token doesn't carry denies that connector. Check that your identity provider includes the claim in the tokens it issues.

Policy and connection changes apply on the user's next request, though the user's client can keep showing its earlier tool list. See When changes take effect.

Tool calls fail with "dial refused"

The gateway refuses to connect to private and loopback addresses unless the connector has Allow private IPs turned on. A gateway log line reading dial refused: private or loopback address names the address; turn on the setting for that connector. A line reading address is never dialable means the endpoint resolves to a link-local or cloud metadata address, which the gateway never connects to; point the connector at a different address.