stacklok · danbarr · Mar 27, 2026 · Mar 27, 2026 · Mar 27, 2026
diff --git a/.husky/pre-commit b/.husky/pre-commit
diff --git a/docs/toolhive/concepts/vmcp.mdx b/docs/toolhive/concepts/vmcp.mdx
@@ -161,9 +161,15 @@ MCPRemoteProxy backends into a single endpoint. The use cases range from simple
 aggregation to complex workflows with approval gates, making it valuable for
 teams managing multiple MCP servers.
 
+## Next steps
+
+- [Try the Quickstart](../guides-vmcp/quickstart.mdx) to deploy your first vMCP
+  on a Kubernetes cluster
+- [Learn how to deploy vMCP](../guides-vmcp/intro.mdx) for a full overview of
+  configuration and architecture
+
 ## Related information
 
-- [Deploy vMCP](../guides-vmcp/intro.mdx)
 - [Configure authentication](../guides-vmcp/authentication.mdx)
 - [Tool aggregation and conflict resolution](../guides-vmcp/tool-aggregation.mdx)
 - [Composite tools and workflows](../guides-vmcp/composite-tools.mdx)

diff --git a/docs/toolhive/faq.mdx b/docs/toolhive/faq.mdx
@@ -62,13 +62,13 @@ from the web using the
 [GoFetch MCP server](https://github.com/StacklokLabs/gofetch), and for popular
 services and platforms like:
 
-- **Atlassian** – Access Jira and Confluence
-- **AWS Documentation** – Query AWS service documentation
-- **GitHub** – Access repositories, issues, and pull requests
-- **Kubernetes** – Interact with Kubernetes clusters via the
+- **Atlassian** - Access Jira and Confluence
+- **AWS Documentation** - Query AWS service documentation
+- **GitHub** - Access repositories, issues, and pull requests
+- **Kubernetes** - Interact with Kubernetes clusters via the
   [MKP MCP server](https://github.com/StacklokLabs/mkp)
-- **MongoDB**, **PostgreSQL**, **Redis** – Connect to databases
-- **Notion** – Connect to Notion workspaces
+- **MongoDB**, **PostgreSQL**, **Redis** - Connect to databases
+- **Notion** - Connect to Notion workspaces
 - And many more
 
 ### Can I run MCP servers that aren't in the registry?
@@ -158,8 +158,8 @@ ToolHive provides secure secrets management:
 
 Yes. ToolHive uses permission profiles to control:
 
-- **File system access** – Which directories the server can read or write
-- **Network access** – Which hosts and ports the server can connect to
+- **File system access** - Which directories the server can read or write
+- **Network access** - Which hosts and ports the server can connect to
 
 You can use built-in profiles or create custom ones for specific security
 requirements.
@@ -213,21 +213,21 @@ Yes. ToolHive supports corporate environments with:
 
 ### Where can I get help if I'm stuck?
 
-- **Documentation** – Check the comprehensive guides and reference documentation
-- **GitHub Issues** – Report bugs or request features on the
+- **Documentation** - Check the comprehensive guides and reference documentation
+- **GitHub Issues** - Report bugs or request features on the
   [ToolHive GitHub repository](https://github.com/stacklok/toolhive/issues)
-- **Discord Community** – Join the
+- **Discord Community** - Join the
   [Stacklok Discord](https://discord.gg/stacklok) for community support
-- **Troubleshooting sections** – Each guide includes troubleshooting tips for
+- **Troubleshooting sections** - Each guide includes troubleshooting tips for
   common issues
 
 ### How do I report a bug or request a feature?
 
 Open an issue in the appropriate GitHub repository:
 
-- [**ToolHive UI**](https://github.com/stacklok/toolhive-studio/issues) – For
+- [**ToolHive UI**](https://github.com/stacklok/toolhive-studio/issues) - For
   issues specific to the graphical desktop app
-- [**ToolHive CLI & Kubernetes**](https://github.com/stacklok/toolhive/issues) –
+- [**ToolHive CLI & Kubernetes**](https://github.com/stacklok/toolhive/issues) -
   For issues related to the CLI tool or Kubernetes operator
 
 ### Is there a community I can join?

diff --git a/docs/toolhive/guides-cli/advanced-cicd.mdx b/docs/toolhive/guides-cli/advanced-cicd.mdx
@@ -310,9 +310,15 @@ When implementing advanced CI/CD patterns:
 6. **Implement change detection** to avoid unnecessary builds
 7. **Store sensitive data** in CI/CD secrets, not in code
 
+## Next steps
+
+- [Deploy to Kubernetes](../guides-k8s/run-mcp-k8s.mdx) to run your CI/CD-built
+  servers in production
+- [Aggregate multiple servers](../guides-vmcp/index.mdx) into a single endpoint
+  with Virtual MCP Server
+
 ## Related information
 
 - [Build MCP server containers](./build-containers.mdx)
-- [Run MCP servers in Kubernetes](../guides-k8s/run-mcp-k8s.mdx)
 - [`thv build` command reference](../reference/cli/thv_build.md)
 - [Secrets management](./secrets-management.mdx)
diff --git a/docs/toolhive/guides-cli/api-server.mdx b/docs/toolhive/guides-cli/api-server.mdx
@@ -83,6 +83,12 @@ Open a browser to `http://localhost:8080/api/doc` to view the API documentation.
 The OpenAPI specification is also available at
 `http://localhost:8080/api/openapi.json`.
 
+## Next steps
+
+- [Secure your servers](./auth.mdx) with authentication and authorization
+- [Monitor server activity](./telemetry-and-metrics.mdx) with OpenTelemetry and
+  Prometheus
+
 ## Related information
 
 - [ToolHive API documentation](../reference/api.mdx)

diff --git a/docs/toolhive/guides-cli/auth.mdx b/docs/toolhive/guides-cli/auth.mdx
@@ -143,13 +143,22 @@ to perform an action, ToolHive will evaluate the request against the policies.
 If the request is permitted, the action will proceed; otherwise, it will be
 denied with a 403 Forbidden response.
 
+## Next steps
+
+- [Configure token exchange](./token-exchange.mdx) to let MCP servers
+  authenticate to backend services
+- [Enable telemetry and metrics](./telemetry-and-metrics.mdx) to gain
+  observability into MCP server interactions
+- [Learn about the auth framework](../concepts/auth-framework.mdx) for a deeper
+  understanding of ToolHive's authentication and authorization model
+
 ## Related information
 
-- For conceptual understanding, see
-  [Authentication and authorization framework](../concepts/auth-framework.mdx)
-- For detailed Cedar policy syntax, see
-  [Cedar policies](../concepts/cedar-policies.mdx) and the
-  [Cedar documentation](https://docs.cedarpolicy.com/)
+- [Authentication and authorization framework](../concepts/auth-framework.mdx)
+  for conceptual understanding
+- [Cedar policies](../concepts/cedar-policies.mdx) and the
+  [Cedar documentation](https://docs.cedarpolicy.com/) for detailed policy
+  syntax
 
 ## Troubleshooting
 

diff --git a/docs/toolhive/guides-cli/client-configuration.mdx b/docs/toolhive/guides-cli/client-configuration.mdx
@@ -148,6 +148,12 @@ Example output:
 Configure your client or library to connect to the MCP server using the URL
 ToolHive provides.
 
+## Next steps
+
+- [Set up custom permissions](./custom-permissions.mdx) to control filesystem
+  and network access for your servers
+- [Secure your servers](./auth.mdx) with OIDC authentication and Cedar policies
+
 ## Related information
 
 - [`thv client` command reference](../reference/cli/thv_client.md)

diff --git a/docs/toolhive/guides-cli/custom-permissions.mdx b/docs/toolhive/guides-cli/custom-permissions.mdx
@@ -229,6 +229,11 @@ When creating and using permission profiles:
 - Keep permission profiles in version control to track changes and share them
   with your team
 
+## Next steps
+
+- [Set up authentication](./auth.mdx) for user-level access control with OIDC
+  and Cedar policies
+
 ## Related information
 
 - [`thv run` command reference](../reference/cli/thv_run.md)

diff --git a/docs/toolhive/guides-cli/filesystem-access.mdx b/docs/toolhive/guides-cli/filesystem-access.mdx
@@ -217,6 +217,13 @@ container, use the server's `--db` flag to specify the new path:
 thv run --volume ~/my-database.db:/data/my-database.db sqlite -- --db /data/my-database.db
 ```
 
+## Next steps
+
+- [Exclude sensitive files](./thvignore.mdx) from MCP server access with
+  `.thvignore`
+- [Restrict network access](./network-isolation.mdx) to control outbound
+  connections
+
 ## Related information
 
 - [`thv run` command reference](../reference/cli/thv_run.md)

diff --git a/docs/toolhive/guides-cli/group-management.mdx b/docs/toolhive/guides-cli/group-management.mdx
@@ -120,9 +120,14 @@ Using `--with-workloads` permanently deletes all servers in the group.
 
 :::
 
+## Next steps
+
+- [Configure your AI client](./client-configuration.mdx) to connect to your
+  server groups
+- [Manage secrets](./secrets-management.mdx) for the MCP servers in your groups
+
 ## Related information
 
-- [Client configuration](client-configuration.mdx)
 - [Run MCP servers](run-mcp-servers.mdx)
 - [`thv group` command reference](../reference/cli/thv_group.md)
 - [`thv client` command reference](../reference/cli/thv_client.md)
diff --git a/docs/toolhive/guides-cli/manage-mcp-servers.mdx b/docs/toolhive/guides-cli/manage-mcp-servers.mdx
@@ -151,11 +151,19 @@ thv start <REMOTE_SERVER_NAME>
 
 This will always prompt for re-authentication, even if valid tokens exist.
 
+## Next steps
+
+- [Organize servers into groups](./group-management.mdx) to manage related
+  servers together
+- [Monitor server activity](./telemetry-and-metrics.mdx) with OpenTelemetry and
+  Prometheus
+- [Configure your AI client](./client-configuration.mdx) to connect to your
+  servers
+
 ## Related information
 
 - [`thv list` command reference](../reference/cli/thv_list.md)
 - [`thv logs` command reference](../reference/cli/thv_logs.md)
 - [`thv stop` command reference](../reference/cli/thv_stop.md)
 - [`thv start` command reference](../reference/cli/thv_start.md)
 - [`thv rm` command reference](../reference/cli/thv_rm.md)
-- [Monitor with OpenTelemetry](../guides-cli/telemetry-and-metrics.mdx)
diff --git a/docs/toolhive/guides-cli/network-isolation.mdx b/docs/toolhive/guides-cli/network-isolation.mdx
@@ -318,6 +318,11 @@ default behavior of allowing traffic only from the container's own hostname,
 
 :::
 
+## Next steps
+
+- [Set up authentication](./auth.mdx) for user-level access control with OIDC
+  and Cedar policies
+
 ## Related information
 
 - [`thv run` command reference](../reference/cli/thv_run.md)

diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx
@@ -888,11 +888,14 @@ The configuration file must contain all server settings.
 
 ## Next steps
 
-See [Monitor and manage MCP servers](./manage-mcp-servers.mdx) to monitor and
-control your servers.
-
-[Test your MCP server](./test-mcp-servers.mdx) using the MCP Inspector or
-`thv mcp` commands.
+- [Monitor and manage MCP servers](./manage-mcp-servers.mdx) to control your
+  running servers
+- [Test your MCP servers](./test-mcp-servers.mdx) using the MCP Inspector or
+  `thv mcp` commands
+- [Secure your servers](./auth.mdx) with OIDC authentication and Cedar policies
+- [Enable telemetry and metrics](./telemetry-and-metrics.mdx) to gain
+  observability into MCP server interactions
+- [Run the API server](./api-server.mdx) for programmatic access to ToolHive
 
 ## Related information
 

diff --git a/docs/toolhive/guides-cli/secrets-management.mdx b/docs/toolhive/guides-cli/secrets-management.mdx
@@ -267,10 +267,17 @@ This command retrieves the `token` and `team_id` fields from the `slackbot` item
 in the `MCPVault` vault and passes them to the `slack` MCP server as the
 `SLACK_BOT_TOKEN` and `SLACK_TEAM_ID` environment variables.
 
+## Next steps
+
+- [Configure your AI client](./client-configuration.mdx) to connect to your
+  servers
+- [Set up custom permissions](./custom-permissions.mdx) to control filesystem
+  and network access
+
 ## Related information
 
 - [`thv secret` command reference](../reference/cli/thv_secret.md)
-- [Run MCP servers](../guides-cli/run-mcp-servers.mdx)
+- [Run MCP servers](./run-mcp-servers.mdx)
 
 ## Troubleshooting
 

diff --git a/docs/toolhive/guides-cli/telemetry-and-metrics.mdx b/docs/toolhive/guides-cli/telemetry-and-metrics.mdx
@@ -406,6 +406,15 @@ Telemetry adds minimal overhead when properly configured:
 - Use appropriate sampling rates for your traffic volume
 - Monitor your observability backend costs and adjust sampling accordingly
 
+## Next steps
+
+- [Learn about ToolHive's observability model](../concepts/observability.mdx)
+  for a deeper understanding of the telemetry architecture
+- [Monitor and manage MCP servers](./manage-mcp-servers.mdx) for server
+  lifecycle management including logs and status monitoring
+- [Collect telemetry for MCP workloads](../integrations/opentelemetry.mdx) for a
+  hands-on tutorial with an OpenTelemetry Collector
+
 ## Related information
 
 - Tutorial:

diff --git a/docs/toolhive/guides-cli/test-mcp-servers.mdx b/docs/toolhive/guides-cli/test-mcp-servers.mdx
@@ -89,6 +89,14 @@ and see how your MCP server responds to various prompts.
 See [Test MCP servers in the ToolHive UI](../guides-ui/playground.mdx) to learn
 about the playground's features and how to get started.
 
+## Next steps
+
+- [Build MCP containers](./build-containers.mdx) to package your tested servers
+  for deployment
+- [Set up CI/CD patterns](./advanced-cicd.mdx) to automate testing in your
+  pipeline
+- [Secure your servers](./auth.mdx) with authentication and authorization
+
 ## Related information
 
 - [`thv inspector` command reference](../reference/cli/thv_inspector.md)

diff --git a/docs/toolhive/guides-cli/thvignore.mdx b/docs/toolhive/guides-cli/thvignore.mdx
@@ -128,6 +128,11 @@ example, `.env*`, build artifacts) in your project's local `.thvignore`.
 
 </details>
 
+## Next steps
+
+- [Restrict network access](./network-isolation.mdx) to control outbound
+  connections from MCP servers
+
 ## Related information
 
 - [File system access](./filesystem-access.mdx)

diff --git a/docs/toolhive/guides-cli/token-exchange.mdx b/docs/toolhive/guides-cli/token-exchange.mdx
@@ -200,6 +200,12 @@ Key points in this example:
   (`api:read`, `api:write`). The user's identity is preserved, but the
   permissions are transformed for the target service.
 
+## Next steps
+
+- [Monitor server activity](./telemetry-and-metrics.mdx) with OpenTelemetry and
+  Prometheus
+- [Test your MCP servers](./test-mcp-servers.mdx) to validate your configuration
+
 ## Related information
 
 - [Backend authentication](../concepts/backend-auth.mdx) - conceptual overview

diff --git a/docs/toolhive/guides-k8s/auth-k8s.mdx b/docs/toolhive/guides-k8s/auth-k8s.mdx
@@ -476,7 +476,7 @@ kubectl apply -f embedded-auth-config.yaml
 
 The MCPServer needs two configuration references: `externalAuthConfigRef`
 enables the embedded authorization server, and `oidcConfig` validates the JWTs
-that the embedded authorization server issues. Unlike approaches 1–3 where
+that the embedded authorization server issues. Unlike approaches 1-3 where
 `oidcConfig` points to an external identity provider, here it points to the
 embedded authorization server itself—the `oidcConfig` issuer must match the
 `issuer` in your `MCPExternalAuthConfig`.
@@ -760,6 +760,13 @@ kubectl logs -n toolhive-system -l app.kubernetes.io/name=weather-server-k8s
 2. Make requests that should be denied
 3. Check the proxy logs to see authorization decisions
 
+## Next steps
+
+- [Configure token exchange](./token-exchange-k8s.mdx) to let MCP servers
+  authenticate to backend services
+- [Set up audit logging](./logging.mdx) to track authentication decisions and
+  MCP server activity
+
 ## Related information
 
 - For conceptual understanding, see

diff --git a/docs/toolhive/guides-k8s/customize-tools.mdx b/docs/toolhive/guides-k8s/customize-tools.mdx
@@ -234,6 +234,12 @@ kubectl -n toolhive-system get mcpserver github -o yaml
 - If an MCPServer references a missing MCPToolConfig, the server enters Failed
   and the controller logs include the missing name and namespace.
 
+## Next steps
+
+- [Secure your servers](./auth-k8s.mdx) with authentication and authorization
+- [Monitor server activity](./telemetry-and-metrics.mdx) with OpenTelemetry and
+  Prometheus
+
 ## Related information
 
 - See the

diff --git a/docs/toolhive/guides-k8s/deploy-operator.mdx b/docs/toolhive/guides-k8s/deploy-operator.mdx
@@ -440,10 +440,9 @@ kubectl delete namespace toolhive-system
 
 ## Next steps
 
-See [Run MCP servers in Kubernetes](./run-mcp-k8s.mdx) to learn how to create
-and manage MCP servers using the ToolHive operator in your Kubernetes cluster.
-The operator supports deploying MCPServer resources based on the deployment mode
-configured during installation.
+- [Run MCP servers in Kubernetes](./run-mcp-k8s.mdx) to create and manage MCP
+  servers using the ToolHive operator
+- [Configure authentication](./auth-k8s.mdx) before exposing servers externally
 
 ## Related information
 

diff --git a/docs/toolhive/guides-k8s/redis-session-storage.mdx b/docs/toolhive/guides-k8s/redis-session-storage.mdx
@@ -595,6 +595,13 @@ session storage is working correctly.
 
 </details>
 
+## Next steps
+
+- [Configure token exchange](./token-exchange-k8s.mdx) to let MCP servers
+  authenticate to backend services
+- [Monitor server activity](./telemetry-and-metrics.mdx) with OpenTelemetry and
+  Prometheus
+
 ## Related information
 
 - [Set up embedded authorization server authentication](./auth-k8s.mdx#set-up-embedded-authorization-server-authentication)