tgrunnagle · Oct 6, 2026 · Oct 5, 2026 · Oct 5, 2026
diff --git a/.github/upstream-projects.yaml b/.github/upstream-projects.yaml
@@ -96,6 +96,11 @@ projects:
     # and will use release_asset: once the platform ships releases.
     docs_paths:
       - docs/platform
+    # Like the CRDs below, synced from the local clone until the
+    # platform ships releases.
+    assets:
+      - source: enterprise/connector-gateway/docs/openapi/swagger.json
+        destination: static/api-specs/connector-gateway-api.json
     crds:
       - source: enterprise/toolhive-enterprise/helm/files/crds
         out: static/api-specs/enterprise-crds

diff --git a/docs/connector-gateway/connectors.mdx b/docs/connector-gateway/connectors.mdx
@@ -7,7 +7,7 @@ description:
 ---
 
 A _connector_ is an MCP server available through the Connector Gateway. After
-registering a connector, grant directory groups access to it.
+registering a connector, grant access to it through its connector policy.
 
 ## The connector list
 
@@ -17,12 +17,30 @@ created.
 
 ## Where connectors come from
 
-Register connectors in one of three ways:
+Select **Add connector** and choose how to register the connector:
 
-- **Import from registry** selects a server from your curated MCP registry.
-- **Add connector** registers one directly by endpoint.
-- **Discovery** picks up MCP servers running in your cluster automatically.
-  Those arrive with a description noting the namespace they were found in.
+- **Import from registry** adds remote servers that your curated MCP registry
+  publishes.
+- **Discover in Kubernetes** scans your cluster for running MCP servers and lets
+  you choose which ones to add.
+- **Configure manually** registers a server by name, endpoint, and transport.
+
+### Add MCP servers from your cluster
+
+Discovery lists every `MCPServer` resource in your cluster, across all
+namespaces, as a candidate. Nothing is registered until you select candidates
+and choose **Add to catalog**.
+
+Each candidate shows its namespace, transport, and endpoint. If an existing
+connector already uses a candidate's endpoint, the candidate shows **Already
+added as** and the connector's name. A candidate that belongs to an MCP server
+group shows that group, because a vMCP might already aggregate it and adding it
+separately would expose its tools twice. If discovery can't determine a
+candidate's transport, choose one before adding it.
+
+Each server you add becomes a **Draft** connector with no backend authentication
+and a description naming the namespace it came from. Open the connector to
+review its configuration, then save it to publish the connector.
 
 ## Draft, available, and failure
 
@@ -32,18 +50,28 @@ invalid or unreachable endpoint enters **Failure**.
 
 ## Granting access
 
-Open a connector and use **Grant access** to add one or more groups. Membership
-is inherited, so granting to a parent group reaches every subgroup beneath it.
-
-The Connector Gateway evaluates access on every request, so changes take effect
-on the next request.
+Each connector has a connector policy that decides who can use it. The policy
+has two authoring modes:
 
-:::warning
+- **Structured** mode grants access to directory groups. This is the mode the
+  console manages.
+- **Cedar** mode uses a Cedar policy document. A document can match directory
+  group (`UserGroup`) membership, custom claims from the caller's token such as
+  `principal.claim_department`, or both.
 
-Connector grants use **directory groups**. See
+To grant access in structured mode, open a connector and use **Grant access** to
+add one or more groups. Membership is inherited, so granting to a parent group
+reaches every subgroup beneath it. Directory groups are separate from the OIDC
+claim groups that cluster authorization policy matches. See
 [Directory groups and OIDC claim groups](../platform/concepts/two-group-models.mdx).
 
-:::
+The console doesn't edit Cedar-mode policies. For a Cedar-mode connector, it
+shows a notice and disables group editing. Switch modes and write Cedar
+documents through the connector policy routes of the
+[Enterprise Manager API](../platform/enterprise-platform/api-reference.mdx#enterprise-manager).
+
+The Connector Gateway evaluates access on every request, so changes take effect
+on the next request.
 
 ## Connector authentication
 

diff --git a/docs/connector-gateway/index.mdx b/docs/connector-gateway/index.mdx
@@ -16,8 +16,8 @@ The Connector Gateway is a component of Stacklok Enterprise.
 :::
 
 The Connector Gateway provides an identity-aware endpoint for MCP tool calls. It
-uses directory group grants to expose the connectors available to each caller
-and brokers connector credentials on their behalf.
+evaluates each connector's policy to expose the connectors available to each
+caller and brokers connector credentials on their behalf.
 
 It is the counterpart to the [AI Gateway](../ai-gateway/index.mdx). The AI
 Gateway governs the **models** your agents can call; the Connector Gateway
@@ -38,16 +38,16 @@ cluster.
 ## What you administer here
 
 - Register MCP servers as connectors.
-- Grant connector access to directory groups.
+- Grant connector access to directory groups or through Cedar policies.
 - Review tool calls by connector and tool.
 
 ## Before you start
 
 Deploy and configure the Connector Gateway before administering connectors. See
 [Configure the Connector Gateway](../platform/enterprise-platform/configure-connector-gateway.mdx).
 
-Connector grants use directory groups. Cluster authorization policy uses OIDC
-claim groups. See
+Structured connector grants use directory groups. Cluster authorization policy
+uses OIDC claim groups. See
 [Directory groups and OIDC claim groups](../platform/concepts/two-group-models.mdx).
 
 ## Contents

diff --git a/docs/platform/concepts/two-group-models.mdx b/docs/platform/concepts/two-group-models.mdx
@@ -6,16 +6,18 @@ description:
   authorization policy.
 ---
 
-Stacklok Enterprise uses directory groups for connector access and budgets. It
-uses OpenID Connect (OIDC) claim groups for cluster authorization policy. Choose
-the group model that matches the control you are configuring.
+Stacklok Enterprise uses directory groups for budgets and structured connector
+policies. It uses OpenID Connect (OIDC) claim groups for cluster authorization
+policy. Cedar-mode connector policies can match directory groups, token claims,
+or both. Choose the group model that matches the control you are configuring.
 
-| Control                                               | Group model      |
-| ----------------------------------------------------- | ---------------- |
-| Connector access                                      | Directory group  |
-| AI Gateway budget                                     | Directory group  |
-| `PlatformRoleBinding` or `ClusterPlatformRoleBinding` | OIDC claim group |
-| `ToolhiveAuthorizationPolicy`                         | OIDC claim group |
+| Control                                               | Group model                    |
+| ----------------------------------------------------- | ------------------------------ |
+| Connector access, structured policy                   | Directory group                |
+| Connector access, Cedar policy                        | Directory group or token claim |
+| AI Gateway budget                                     | Directory group                |
+| `PlatformRoleBinding` or `ClusterPlatformRoleBinding` | OIDC claim group               |
+| `ToolhiveAuthorizationPolicy`                         | OIDC claim group               |
 
 ## Directory groups
 
@@ -24,9 +26,24 @@ and membership list. Administrators can manage directory groups in the console
 or provision them from an identity provider through System for Cross-domain
 Identity Management (SCIM).
 
-The Connector Gateway resolves each caller to a directory user and uses their
-group memberships to determine connector access. AI Gateway group budgets also
-reference the directory group's identifier.
+The Connector Gateway resolves each caller to a directory user, and the
+directory evaluates each connector's policy against that user. A structured-mode
+policy grants access to directory groups. A Cedar-mode policy can match
+directory group (`UserGroup`) membership, claims from the caller's token such as
+`principal.claim_department`, or both. See
+[Granting access](../../connector-gateway/connectors.mdx#granting-access) for
+the two modes. AI Gateway group budgets also reference the directory group's
+identifier.
+
+:::note[Cedar-mode policies are API-only]
+
+The console edits structured-mode grants only. To switch a connector to Cedar
+mode or write its Cedar document, use the connector policy routes of the
+[Enterprise Manager API](../enterprise-platform/api-reference.mdx#enterprise-manager).
+For a Cedar-mode connector, the console shows a notice and disables group
+editing.
+
+:::
 
 ## OIDC claim groups
 

diff --git a/docs/platform/enterprise-directory/index.mdx b/docs/platform/enterprise-directory/index.mdx
@@ -39,8 +39,8 @@ matching record.
 
 :::warning
 
-Connector access and budgets use directory groups. Cluster authorization policy
-uses OIDC claim groups. See
+Budgets and structured connector policies use directory groups. Cluster
+authorization policy uses OIDC claim groups. See
 [Directory groups and OIDC claim groups](../concepts/two-group-models.mdx).
 
 :::

diff --git a/docs/platform/enterprise-platform/api-reference.mdx b/docs/platform/enterprise-platform/api-reference.mdx
@@ -45,8 +45,11 @@ routes. Use `/api/doc` on the running service for its complete API reference.
 
 ## Connector Gateway
 
-The Connector Gateway API covers connector enablement and per-user authorization
-state. See [Configure the Connector Gateway](./configure-connector-gateway.mdx).
+The Connector Gateway API serves the calling user's view of the gateway: each
+connector's upstream connection status and tools, and the flow that connects a
+connector on the user's behalf. Users enable and disable their connectors
+through the Enterprise Manager's `/v1/me/connections` routes. See
+[Configure the Connector Gateway](./configure-connector-gateway.mdx).
 
 <ApiDocMdx id='connector-gateway-api' />
 

diff --git a/docs/platform/index.mdx b/docs/platform/index.mdx
@@ -218,9 +218,9 @@ documentation that refers to the ToolHive CLI applies to it as well.
 | Identity-aware MCP gateway for tool access, policy enforcement, and per-user configuration. |
 | :------------------------------------------------------------------------------------------ |
 | Integrate with your IdP for SSO (OIDC/OAuth compatible)                                     |
-| Build composite tools that orchestrate multiple tools in parallel or sequential chains      |
-| Customize and filter tools and descriptions                                                 |
-| Reduce context bloat and token usage                                                        |
+| Control connector access per user with directory groups or Cedar policies                   |
+| Broker connector credentials on each user's behalf                                          |
+| Discover MCP servers in your cluster and add them as connectors                             |
 | Connect with local clients like Claude Desktop, Cursor, and VS Code                         |
 
 ### AI Gateway