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, Verification state, Endpoint, Transport, Groups with access, and Created date. Search by name or description, or filter by Verification state.

To make a connector available to users, add it, confirm it passes verification, set up its authentication, and grant access to at least one directory group.

Add a connector

Select Add connector, then choose how to add it: Import from registry, Discover in Kubernetes, or Configure manually. Each method leaves the connector in a different state, described in its section.

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

Import from registry

Import adds remote MCP servers that your curated MCP registry publishes. The dialog lists remote servers only; container-only servers don't appear.

1. Select Add connector, then Import from registry.
2. Choose a Registry, then select the servers to add.
3. If the registry doesn't report a server's transport, choose one for it.
4. Select Add to Connectors.

Imported connectors publish immediately with no authentication, so the console verifies each one as soon as it's added. For a server that needs credentials, set up its authentication next.

Discover in Kubernetes

Discovery lists the MCPServer resources running in your cluster.

1. Select Add connector, then Discover in Kubernetes.
2. Select the servers to add. If a server's transport is unknown, choose one for it.
3. Select Add to catalog.

Discovered servers arrive as drafts, and the gateway withholds them until you publish them. Each draft opens on its Configuration tab with a Setup required banner. Review its settings, then verify and publish it.

Discovery 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.

Configure manually

Configure any running MCP server by hand.

1. Select Add connector, then Configure manually.
2. Enter a name, the endpoint, and the transport. For an in-cluster endpoint, turn on Allow private IPs.
3. Choose an authentication type and fill in its fields. See Configure connector authentication.
4. Select Add connector.

A manually configured connector publishes on create, and the console verifies it right away.

Verify and publish a connector

Verification checks 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 Verification state:

State	Meaning
Draft	Added through discovery and not yet saved. The gateway withholds it.
Verifying	Verification is running.
Verified	Verification passed. The gateway serves the connector.
Broken	Verification failed. The gateway withholds it.

To publish a draft, or to retry a broken connector:

1. Open the connector and select the Configuration tab.
2. Review the endpoint, transport, and authentication settings, and fix anything that caused a failure.
3. Select Save and verify.

A verified connector re-verifies when you change its endpoint, authentication, or Allow private IPs setting. Verification runs only when you save, so a connector stays Verified if its backend later goes down. If calls start failing, check the backend itself.

The console doesn't show why verification failed. See A connector shows Broken 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. On the connector's Configuration tab, turn on Allow private IPs (allow_private_ips in the API). The setting also permits plain HTTP. Discovery 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 Enterprise Manager's verification allowlist. Verification 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:
           - '10.96.0.0/12'

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 connector's Configuration tab and save to re-verify.

Some types reference a managed secret or a connector identity provider, which must exist before you save. 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 tool calls, with the Tool, User, Time, and Outcome (Allowed or Denied) of each one.

• Filter by Outcome to show only allowed or denied calls.
• 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. For a complete per-request record, 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, change its settings on the Configuration tab and save. Changes to the endpoint, authentication, or Allow private IPs setting re-verify the connector.

To delete a connector, open it, select Delete, 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 Broken

The console doesn't display the verification error. Find it in the Enterprise Manager's logs, on a connector write persisted as failure line with the connector's ID and an err field:

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. The error reads resolves to a disallowed IP range. 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 and select Save and verify. A broken connector stays broken 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 saving fails with "This endpoint resolves to a disallowed (private or reserved) IP range", turn on Allow private IPs for the connector.
• If the connector saves but shows Broken, and the Enterprise Manager log reads resolves to a disallowed IP range, add the address range to enterprise-manager.directory.connectorVerification.allowedPrivateRanges.

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 verified 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 Verified.
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.