diff --git a/AGENTS.md b/AGENTS.md index 70258cd4..03d94a7c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -253,6 +253,7 @@ ALWAYS use these exact terms and capitalizations. When editing documentation, re - Stacklok Enterprise - the commercial, enterprise-licensed distribution of ToolHive, adding turnkey IdP integration, centralized policy enforcement, hardened and signed releases, and SLA-backed support - Enterprise Manager - the Stacklok Enterprise component that pushes policy configuration to the Stacklok CLI - the console - the Stacklok Enterprise web interface, covering both the administration and end-user experiences. Lowercase in running prose; it is a common noun, not a product name (not "Enterprise Cloud UI", "Cloud UI", or "Enterprise UI"). Distinct from the open source ToolHive Cloud UI, which is retired and keeps its own name on the page that records the retirement. Its Helm identifiers keep their original spelling: the enable flag is `cloudUi` and the subchart key is `toolhive-cloud-ui`, so use those verbatim in values examples +- administration experience, user experience - the console's two experiences, selected under **Experience** in the account menu. Use the exact, bolded UI labels in selection instructions, such as "select **Administration**" or "select **User**." In running prose, write "the administration experience" and "the user experience." Avoid "Your workspace," which is not a console label. - Stacklok Desktop - retired. The enterprise desktop app no longer ships and no page should reference it; the enterprise client is the Stacklok CLI - engineering codenames and route prefixes are internal. Use the product name in published content, and never document a URL path that exists only as an implementation detail - enterprise authorization - the Stacklok Enterprise capability that compiles RBAC-style custom resources (roles, bindings, and per-server attachment policies) into the Cedar policies ToolHive enforces. It is a feature, not a named component: write it lowercase, capitalizing only at the start of a sentence, heading, or title. Don't treat it as a proper noun like the Enterprise Manager. diff --git a/STYLE-GUIDE.md b/STYLE-GUIDE.md index 8d2995d4..5f8a977f 100644 --- a/STYLE-GUIDE.md +++ b/STYLE-GUIDE.md @@ -426,6 +426,13 @@ administration and end-user experiences. Lowercase in running prose, since it is a common noun rather than a product name. Not "Enterprise Cloud UI", "Cloud UI", or "Enterprise UI". +The console has two experiences, **Administration** and **User**, and +administrators switch between them under **Experience** in the account menu. Use +the exact, bolded UI labels in selection instructions, such as "select +**Administration**" or "select **User**." In running prose, write "the +administration experience" and "the user experience." Avoid "Your workspace," +which is not a console label. + This is a different product from the open source ToolHive Cloud UI, which is retired and keeps its own name on the page that records the retirement. diff --git a/docs/connector-gateway/index.mdx b/docs/connector-gateway/index.mdx index 2dddad23..dec20f1b 100644 --- a/docs/connector-gateway/index.mdx +++ b/docs/connector-gateway/index.mdx @@ -5,8 +5,6 @@ description: their tools are used. --- -import DocCardList from '@theme/DocCardList'; - :::enterprise The Connector Gateway is a component of Stacklok Enterprise. @@ -120,6 +118,9 @@ cluster. credentials. See [Set up the prerequisites in order](./connector-authentication.mdx#set-up-the-prerequisites-in-order). -## Contents +## Next steps - +- [Try the Connector Gateway quickstart](./quickstart.mdx) to register a + connector and call it from an MCP client. +- [Manage connectors](./connectors.mdx) to register the MCP servers your + organization needs. diff --git a/docs/connector-gateway/quickstart.mdx b/docs/connector-gateway/quickstart.mdx index a12f38b4..8719ee86 100644 --- a/docs/connector-gateway/quickstart.mdx +++ b/docs/connector-gateway/quickstart.mdx @@ -29,7 +29,7 @@ both the administrator and the user. ## Step 1: Register the connector -1. In the console's Administration experience, open **Connectors** and select +1. In the console's administration experience, open **Connectors** and select **Add connector**. 2. Choose **Configure manually** and fill in the form: - **Name**: `DeepWiki` @@ -94,7 +94,7 @@ through the Connector Gateway and answers from DeepWiki's response. ## Step 6: See the call in Tool Usage -1. Switch back to the Administration experience and open **Tool Usage** under +1. Switch back to the administration experience and open **Tool Usage** under **Connectors**. 2. With **Last 24h** selected, find DeepWiki on the **By connector** tab. Its call count includes your call. diff --git a/docs/connector-gateway/support-connector-access.mdx b/docs/connector-gateway/support-connector-access.mdx index c7236b11..d049b82a 100644 --- a/docs/connector-gateway/support-connector-access.mdx +++ b/docs/connector-gateway/support-connector-access.mdx @@ -23,13 +23,13 @@ applies to every client that signs in to the gateway as them. ## Where users manage connections -Users manage connections in the console's User experience, under **Connectors** +Users manage connections in the console's user experience, under **Connectors** in the **Gateways** group. The **Tools** tab lists the connectors granted to them: connectors they've connected to appear under **Enabled**, and the rest appear under **Available**. To see what a user sees, open the account menu and choose **User** under -**Experience**. The User experience shows the connectors granted to your own +**Experience**. The user experience shows the connectors granted to your own account, so use a test account in the same groups as the user to reproduce their view. diff --git a/docs/platform/enterprise-directory/index.mdx b/docs/platform/enterprise-directory/index.mdx index a53b5744..be0251b7 100644 --- a/docs/platform/enterprise-directory/index.mdx +++ b/docs/platform/enterprise-directory/index.mdx @@ -49,7 +49,8 @@ authorization policy uses OIDC claim groups. See Use **User management** for users, groups, and subgroups. Use **Identity providers** and **Managed secrets** for connector authentication. Users manage -their virtual keys under **API keys** in **Your workspace**. +their virtual keys on the **API Keys** tab under **AI Gateway** in the console's +user experience. The platform admin grant covers directory and budget administration. Use the `/v1` API for automation and bulk changes. diff --git a/docs/platform/enterprise-directory/virtual-api-keys.mdx b/docs/platform/enterprise-directory/virtual-api-keys.mdx index ae4b67cc..f2e81da6 100644 --- a/docs/platform/enterprise-directory/virtual-api-keys.mdx +++ b/docs/platform/enterprise-directory/virtual-api-keys.mdx @@ -13,8 +13,10 @@ audit attribution. ## Where to find them -Users manage their keys under **API keys** in **Your workspace**. Administrators -can list and disable other users' keys through the API. +Users manage their own keys in the console's user experience. Open the account +menu and choose **User** under **Experience**, then select **AI Gateway** under +**Gateways** and open the **API Keys** tab. Administrators can list and disable +other users' keys through the API. ## Prerequisites @@ -26,7 +28,7 @@ console. ## Issue a key -1. Open **API keys** in the console. +1. Open the **API Keys** tab under **AI Gateway** in the console. 2. Use **Create key** and give it a name that says where it will be used. 3. Copy the value immediately. It is shown once and cannot be retrieved afterwards; only its prefix is stored for identification. diff --git a/docs/platform/enterprise-platform/roll-out-gateway-clients.mdx b/docs/platform/enterprise-platform/roll-out-gateway-clients.mdx index c4940ad7..e3ce6de3 100644 --- a/docs/platform/enterprise-platform/roll-out-gateway-clients.mdx +++ b/docs/platform/enterprise-platform/roll-out-gateway-clients.mdx @@ -2,24 +2,43 @@ title: Roll out gateway clients sidebar_label: Roll out gateway clients description: - Direct users to deployment-specific client setup and choose authentication - methods for interactive and automated clients. + Prepare access, budgets, and network reachability before users connect their + clients to the gateways, then point them to the console and support them. --- -After you deploy the gateways, direct users to the setup instructions in the -console. The console supplies the endpoints and client-specific configuration -for your deployment. +Rolling out the gateways means preparing access, sending users to the console, +and supporting them once they connect. The console carries the +deployment-specific endpoints and per-client setup guides, so you don't need to +write client setup instructions for your users. -## Choose the gateway endpoints +## Prepare access -Clients can use either or both gateways: +Before you announce the rollout: -- Send OpenAI-compatible model traffic to the **AI Gateway**. -- Send MCP tool calls to the **Connector Gateway**. +- Assign an [AI Gateway budget](../../ai-gateway/manage-budgets.mdx) to each + user or group that will send model traffic. +- [Grant directory groups access](../../connector-gateway/connector-policies.mdx) + to the connectors they need. +- Set up the [managed secrets](../../connector-gateway/managed-secrets.mdx) and + [identity providers](../../connector-gateway/identity-providers.mdx) those + connectors use. Users of a connector with per-user sign-in authorize it once, + when they connect. +- Turn on + [tool call recording](../../connector-gateway/tool-usage.mdx#record-tool-calls) + if you want to track adoption from the first day. -Users can open **Setup** in each gateway area of **Your workspace** for -deployment-specific instructions. This keeps endpoint details out of rollout -documentation and supports the clients listed in the console. +To check the experience before users do, follow the +[Connector Gateway quickstart](../../connector-gateway/quickstart.mdx) with a +test account. + +## Check network reachability + +Most MCP clients, such as Claude Code, Cursor, and VS Code, connect to the +Connector Gateway from the user's machine. Claude on the web and Claude Desktop +connect from Anthropic's cloud instead, so they work only when the gateway +endpoint is reachable from the public internet. If your gateway sits on a +private network, behind a VPN, or behind a firewall, tell users which clients to +use. ## Choose an authentication method @@ -29,20 +48,30 @@ documentation and supports the clients listed in the console. scripts, scheduled jobs, continuous integration, and other clients without a browser flow. Requests remain attributed to the key owner. -## Prepare access before rollout +## Point users to the console + +Send users the console URL for your deployment. They sign in with their +corporate identity and find both gateways under **Gateways**: + +- **Connectors**: connect to the connectors granted to them on the **Tools** + tab, then set up an MCP client from the **Clients** tab. The **Clients** tab + has the gateway endpoint, a prompt that an AI coding assistant can use to + configure itself, and setup guides for common clients. +- **AI Gateway**: the **Clients** tab has the model gateway URL and setup guides + for routing model traffic, and the **API Keys** tab issues virtual API keys. + +In your announcement, list the connectors each group can use, any connectors +that ask for a sign-in, and where users should ask for help. -Before distributing the setup instructions: +## Support users -- Assign an AI Gateway budget to each user or group that will send model - traffic. -- Grant directory groups access to the required connectors. -- Tell users to connect to their connectors in the console before using them, - and to sign in when a connector requires OAuth. See - [Support users' connector access](../../connector-gateway/support-connector-access.mdx). +When a user can't reach a connector's tools, see +[Support users' connector access](../../connector-gateway/support-connector-access.mdx) +for the connection states users see and the checks to run. ## Next steps -- [Manage budgets](../../ai-gateway/manage-budgets.mdx) before enabling model - traffic. -- [Manage connectors](../../connector-gateway/connectors.mdx) to grant tool - access. +- [Manage budgets](../../ai-gateway/manage-budgets.mdx) to adjust spending + limits as usage grows. +- [Review tool usage](../../connector-gateway/tool-usage.mdx) to track adoption + after rollout. diff --git a/sidebars.ts b/sidebars.ts index 7b666688..189c2493 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -463,12 +463,33 @@ const connectorGatewaySidebar: SidebarsConfig[string] = [ className: 'enterprise-only enterprise-only--tooltip-below', }, 'connector-gateway/quickstart', + + { + type: 'html', + value: 'Configure and secure', + className: 'sidebar-title', + defaultStyle: false, + }, 'connector-gateway/connectors', - 'connector-gateway/connector-authentication', 'connector-gateway/managed-secrets', 'connector-gateway/identity-providers', + 'connector-gateway/connector-authentication', 'connector-gateway/connector-policies', + + { + type: 'html', + value: 'Roll out and support', + className: 'sidebar-title', + defaultStyle: false, + }, 'connector-gateway/support-connector-access', + + { + type: 'html', + value: 'Operate', + className: 'sidebar-title', + defaultStyle: false, + }, 'connector-gateway/tool-usage', 'connector-gateway/telemetry', 'connector-gateway/forward-audit-logs', diff --git a/tests/visual/pages.spec.ts-snapshots/nav-page-connector-gateway-dark-desktop-linux.png b/tests/visual/pages.spec.ts-snapshots/nav-page-connector-gateway-dark-desktop-linux.png index 3c3e39cb..049416fb 100644 Binary files a/tests/visual/pages.spec.ts-snapshots/nav-page-connector-gateway-dark-desktop-linux.png and b/tests/visual/pages.spec.ts-snapshots/nav-page-connector-gateway-dark-desktop-linux.png differ diff --git a/tests/visual/pages.spec.ts-snapshots/nav-page-connector-gateway-light-desktop-linux.png b/tests/visual/pages.spec.ts-snapshots/nav-page-connector-gateway-light-desktop-linux.png index aa3e3588..f943f83f 100644 Binary files a/tests/visual/pages.spec.ts-snapshots/nav-page-connector-gateway-light-desktop-linux.png and b/tests/visual/pages.spec.ts-snapshots/nav-page-connector-gateway-light-desktop-linux.png differ