stacklok · danbarr · Jul 16, 2025 · Jul 15, 2025 · Jul 16, 2025
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,24 @@
+### Description
+<!-- Explain what has changed and why -->
+
+### Related issues/PRs
+<!-- Reference related issues the PR is related to or will resolve -->
+<!-- If documenting a new feature, link to the related PR in the main project's repo -->
+
+### Screenshots
+<!-- Optionally include screenshots if needed to show new formatting or sidebar structure -->
+
+### Merge checklist
+<!-- If items don't apply, add (N/A) and mark them as complete. -->
+
+#### Content
+
+- [ ] New pages include a frontmatter section with title and description at a minimum
+- [ ] Sidebar navigation (`sidebars.ts`) updated for added, deleted, reordered, or renamed files
+- [ ] Redirects added to `vercel.json` for moved, renamed, or deleted pages (i.e., if the URL slug changed)
+  - Rationale: 404's are the enemy! You can test these in the Vercel preview build (push your branch or run `vercel`)
+
+#### Reviews
+
+- [ ] Content has been reviewed for technical accuracy
+- [ ] Content has been reviewed for spelling, grammar, and [style](STYLE_GUIDE.md)
diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
@@ -1,5 +1,9 @@
 {
   "gitignore": true,
   "globs": ["**/*.md"],
-  "ignores": ["docs/toolhive/reference/cli/", "static/api-specs/*.md"],
+  "ignores": [
+    "docs/toolhive/reference/cli/",
+    "static/api-specs/*.md",
+    ".github/pull_request_template.md",
+  ],
 }
diff --git a/.prettierignore b/.prettierignore
@@ -1,3 +1,6 @@
 # Ignore autogenerated files
 docs/toolhive/reference/cli/**/*.md
 static/api-specs/
+
+# Ignore templates
+.github/pull_request_template.md
diff --git a/docs/theme-preview.mdx b/docs/theme-preview.mdx
@@ -21,7 +21,7 @@ doesn't participate in a sidebar, navigate to a different page to see them.
 
 Another element that can't be easily reproduced here is the DocCardList
 component, but you can see it in action on the
-[ToolHive CLI guides index page](./toolhive/guides-cli).
+[ToolHive CLI guides index page](./toolhive/guides-cli/index.mdx).
 
 ## Level 2 heading
 

diff --git a/docs/toolhive/_partials/_client-config-intro.mdx b/docs/toolhive/_partials/_client-config-intro.mdx
@@ -0,0 +1,17 @@
+ToolHive automatically configures supported AI clients to work with MCP servers.
+This guide shows you how to set up and manage client configurations.
+
+## Understanding client configuration
+
+Before an AI application can use ToolHive MCP servers, it needs to know where to
+find them. You can configure clients in two ways:
+
+1. **{props.term} a supported client**: {props.term} your client with ToolHive
+   so it automatically manages and updates the client's configuration as you
+   start, stop, and remove MCP servers.
+2. **Manual configuration**: For clients that ToolHive doesn't directly support,
+   manually configure them to connect to ToolHive-managed MCP servers using the
+   SSE or Streamable HTTP protocol.
+
+For a complete list of supported clients and compatibility details, see the
+[Client compatibility reference](../reference/client-compatibility.mdx).
diff --git a/docs/toolhive/concepts/_category_.yaml b/docs/toolhive/concepts/_category_.yaml
diff --git a/docs/toolhive/concepts/mcp-primer.md b/docs/toolhive/concepts/mcp-primer.md
@@ -4,7 +4,6 @@ sidebar_label: MCP primer
 description:
   A brief introduction to the Model Context Protocol (MCP) and its benefits for
   developers.
-sidebar_position: 5
 ---
 
 **TL;DR:** MCP offers a pragmatic, language‑friendly bridge between

diff --git a/docs/toolhive/concepts/registry-criteria.md b/docs/toolhive/concepts/registry-criteria.md
@@ -1,10 +1,9 @@
 ---
 title: 'Registry criteria'
 description: Criteria for adding MCP servers to the ToolHive registry
-sidebar_position: 50
 ---
 
-The ToolHive registry maintains a curated list of MCP servers that meet specific
+The ToolHive registry is a curated list of MCP servers that meet specific
 criteria. We aim to establish a curated, community-auditable list of
 high-quality MCP servers through clear, observable, and objective criteria. Here
 are the criteria for adding an MCP server to the ToolHive registry:

diff --git a/docs/toolhive/faq.md b/docs/toolhive/faq.md
@@ -0,0 +1,185 @@
+---
+title: Frequently asked questions
+sidebar_label: FAQ
+description: Common questions about ToolHive.
+---
+
+## General questions
+
+### What is ToolHive?
+
+ToolHive is an open source platform that simplifies the deployment and
+management of Model Context Protocol (MCP) servers. It runs MCP servers in
+secure, isolated containers and provides tools to manage them easily. You can
+run ToolHive as a graphical desktop app, command-line tool, or Kubernetes
+operator.
+
+### What is the Model Context Protocol (MCP)?
+
+MCP is a protocol that allows AI applications to connect to external data
+sources and tools. It provides a standardized way for AI models to access
+real-world context like APIs, source code repositories, databases, and other
+systems. Think of it as a bridge between AI models and the external systems
+where your data and applications live.
+
+### Do I need to know how to code to use ToolHive?
+
+No. ToolHive includes a graphical interface that doesn't require coding
+knowledge. However, some MCP servers may require configuration or secrets, such
+as API keys, that you'll need to set up. The ToolHive CLI is more technical but
+comes with comprehensive documentation.
+
+### Is ToolHive free to use?
+
+Yes, ToolHive is open source (Apache 2.0 licensed) and free to use. You can find
+the source code on GitHub and use it without any licensing fees.
+
+## Using MCP servers
+
+### How do I find available MCP servers?
+
+ToolHive includes a curated registry of verified MCP servers. You can browse
+them from the **Registry** tab in the UI or by running `thv registry list` in
+the CLI.
+
+### What MCP servers are available?
+
+The registry includes servers for common use cases, such as retrieving content
+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
+  [MKP MCP server](https://github.com/StacklokLabs/mkp)
+- **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?
+
+Yes. You can run any MCP server from a container image or source package, even
+if it's not in the registry. Just provide the image name or package details when
+starting the server using the CLI or UI. See the custom MCP server section in
+the [UI guide](./guides-ui/run-mcp-servers.md#install-a-custom-mcp-server) and
+[CLI guide](./guides-cli/run-mcp-servers.mdx#run-a-custom-mcp-server) for more
+details.
+
+The Kubernetes operator also supports custom MCP servers that are packaged as
+container images.
+
+:::tip
+
+You can use the ToolHive CLI to run a custom MCP server from a source package
+once, then export the Docker image for import into your container registry or
+Kubernetes cluster to use it with the operator.
+
+:::
+
+## Security and permissions
+
+### Is it safe to run MCP servers?
+
+ToolHive runs MCP servers in isolated containers with minimal default
+permissions. Each server runs in its own container with restricted access to
+your system and network.
+
+:::tip
+
+For extra security, review the permission profiles and network isolation options
+before running new or untrusted MCP servers.
+
+:::
+
+### How does ToolHive handle secrets like API keys?
+
+ToolHive provides secure secrets management:
+
+- Secrets are encrypted and stored securely on your system
+- They're passed to MCP servers as environment variables
+- Secrets never appear in plaintext in configuration files
+- Integration with 1Password is also supported
+
+### Can I control what an MCP server can access?
+
+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
+
+You can use built-in profiles or create custom ones for specific security
+requirements.
+
+### What's network isolation and when should I use it?
+
+Network isolation creates a secure network architecture that filters all
+outbound connections from MCP servers. Use the `--isolate-network` flag when
+running servers that need strict network controls, especially in enterprise
+environments.
+
+## Enterprise and advanced usage
+
+### Can I use ToolHive in my company?
+
+Yes. ToolHive is designed for both individual developers and enterprise teams.
+The Kubernetes Operator provides centralized management, security controls, and
+integration with existing infrastructure for enterprise deployments.
+
+### How do I deploy ToolHive in Kubernetes?
+
+Use the ToolHive Kubernetes Operator to deploy and manage MCP servers as
+Kubernetes resources. See the [Kubernetes guides](./guides-k8s/index.mdx) for
+detailed instructions. The Kubernetes operator is currently experimental.
+
+### Can I run my own custom MCP servers?
+
+Yes. You can run custom MCP servers from Docker images or source packages.
+ToolHive supports:
+
+- Docker images from public or private registries
+- Source packages from package managers like npm, PyPI, or Go modules
+
+### How do I get my MCP server added to the ToolHive registry?
+
+The ToolHive registry has specific
+[inclusion criteria](./concepts/registry-criteria.md), such as being open
+source, following good security practices, and maintaining code quality. Review
+the criteria and
+[submit your server for consideration](https://github.com/stacklok/toolhive/issues/new?template=add-an-mcp-server.md).
+
+### Can I use ToolHive behind a corporate firewall?
+
+Yes. ToolHive supports corporate environments with:
+
+- Custom CA certificate configuration for TLS inspection
+- Network isolation and permission profiles
+- Integration with secret management systems like 1Password
+
+## Getting help
+
+### 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
+  [ToolHive GitHub repository](https://github.com/stacklok/toolhive/issues)
+- **Discord Community** – Join the
+  [Stacklok Discord](https://discord.gg/stacklok) for community support
+- **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
+  issues specific to the graphical desktop app
+- [**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?
+
+Yes! Join the [Stacklok Discord community](https://discord.gg/stacklok) to
+connect with other ToolHive users, ask questions, and share your experiences.
+There's a dedicated `#toolhive-developers` channel for technical discussions.
diff --git a/docs/toolhive/guides-cli/_category_.yaml b/docs/toolhive/guides-cli/_category_.yaml
diff --git a/docs/toolhive/guides-cli/api-server.md b/docs/toolhive/guides-cli/api-server.md
@@ -1,7 +1,6 @@
 ---
 title: Run the API server
-description: How to run the local ToolHive API server
-sidebar_position: 60
+description: How to run the local ToolHive API server.
 ---
 
 ToolHive includes a built-in API server that provides a RESTful interface for

diff --git a/...olhive/guides-cli/client-configuration.md → ...lhive/guides-cli/client-configuration.mdx b/...olhive/guides-cli/client-configuration.md → ...lhive/guides-cli/client-configuration.mdx
@@ -2,26 +2,11 @@
 title: Client configuration
 description:
   How to configure AI agent clients to work with ToolHive MCP servers.
-sidebar_position: 40
 ---
 
-ToolHive automatically configures supported AI clients to work with MCP servers.
-This guide shows you how to set up and manage client configurations.
+import ClientIntro from '../_partials/_client-config-intro.mdx';
 
-## Understanding client configuration
-
-Before an AI application can use ToolHive MCP servers, it needs to know where to
-find them. You can configure clients in two ways:
-
-1. **Register a supported client**: Register your client with ToolHive so it
-   automatically manages and updates the client's configuration as you start,
-   stop, and remove MCP servers.
-2. **Manual configuration**: For clients that ToolHive doesn't directly support,
-   manually configure them to connect to ToolHive-managed MCP servers using the
-   SSE or Streamable HTTP protocol.
-
-For a complete list of supported clients and compatibility details, see the
-[Client compatibility reference](../reference/client-compatibility.mdx).
+<ClientIntro term='Register' />
 
 ## Register clients
 
@@ -156,7 +141,7 @@ ToolHive provides.
 - [`thv client` command reference](../reference/cli/thv_client.md)
 - [`thv config` command reference](../reference/cli/thv_config.md)
 - [Client compatibility](../reference/client-compatibility.mdx)
-- [Run MCP servers](run-mcp-servers.mdx)
+- [Run MCP servers](./run-mcp-servers.mdx)
 
 ## Troubleshooting
 
@@ -265,9 +250,14 @@ Python-based MCP servers using the Streamable HTTP transport protocol:
 [error] Server exited before responding to `initialize` request.
 ```
 
-This is a known interaction between VS Code and the FastMCP SDK used by
-Python-based MCP servers. If you inspect the HTTP connection, you'll see a
-`307 Temporary Redirect` response, which VS Code doesn't handle correctly.
+This is a known interaction between VS Code and certain versions of the FastMCP
+SDK used by Python-based MCP servers. If you inspect the HTTP connection, you'll
+see a `307 Temporary Redirect` response, which VS Code doesn't handle correctly.
+
+This
+[issue is resolved](https://github.com/modelcontextprotocol/python-sdk/pull/781)
+in the latest versions of the SDK, but if you're using an older version of a
+Python-based MCP server, you might still encounter it.
 
 There are two workarounds:
 
@@ -278,7 +268,4 @@ There are two workarounds:
 2. If the MCP server supports SSE, switch to using the SSE transport instead of
    Streamable HTTP.
 
-You can track a proposed fix for this issue in the
-[MCP Python SDK repository](https://github.com/modelcontextprotocol/python-sdk/pull/781).
-
 </details>
diff --git a/docs/toolhive/guides-cli/custom-permissions.mdx b/docs/toolhive/guides-cli/custom-permissions.mdx
@@ -3,7 +3,6 @@ title: Custom permissions
 description:
   How to create and apply filesystem permissions and network isolation for MCP
   servers using permission profiles in ToolHive.
-sidebar_position: 50
 ---
 
 import Tabs from '@theme/Tabs';
@@ -341,7 +340,7 @@ When creating and using permission profiles:
 ## Related information
 
 - [`thv run` command reference](../reference/cli/thv_run.md)
-- [Run MCP servers](run-mcp-servers.mdx)
+- [Run MCP servers](./run-mcp-servers.mdx)
 
 ## Troubleshooting