+
+
+## Images
+
+An MDX ThemedImage, which switches based on light/dark theme
+([reference](https://docusaurus.io/docs/markdown-features/assets#themed-images))
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import ThemedImage from '@theme/ThemedImage';
+
+Click to expand
+ +This is a details panel, which can be used to show additional information +without cluttering the page. + +It can contain any Markdown or MDX content, including `inline code`, code +blocks, images, even other details panels. +[Here's a link inside the details panel](#details-panel). + +```js title="JavaScript code inside a details panel" +console.log('This is inside a details panel.'); +``` + +
+
+
+ # Follow logs in real-time (like tail -f)
+ thv logs --follow
+
+ # View proxy logs instead of container logs
+ thv logs --proxy
+ ```
+
+
+
+Authentication issues
+ +If clients can't authenticate: + +1. Check that the JWT token is valid and not expired +2. Verify that the audience and issuer match your configuration +3. Ensure the JWKS URL is accessible +4. Check the server logs for specific authentication errors: + + ```bash + # View logs + thv logs
+
diff --git a/versioned_docs/version-1.0/toolhive/_partials/_basic-cedar-config.mdx b/versioned_docs/version-1.0/toolhive/_partials/_basic-cedar-config.mdx
new file mode 100644
index 00000000..86f6b33b
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/_partials/_basic-cedar-config.mdx
@@ -0,0 +1,35 @@
+Create a JSON or YAML file with Cedar policies. This example demonstrates
+several policy patterns:
+
+- Allow everyone to use the weather tool
+- Restrict the admin_tool to a specific user (alice123)
+- Role-based access: only users with the "premium" role can call any tool
+- Attribute-based: allow the calculator tool only for add/subtract operations
+
+Here's an example in JSON format:
+
+```json
+{
+ "version": "1.0",
+ "type": "cedarv1",
+ "cedar": {
+ "policies": [
+ "permit(principal, action == Action::\"call_tool\", resource == Tool::\"weather\");",
+ "permit(principal == Client::\"alice123\", action == Action::\"call_tool\", resource == Tool::\"admin_tool\");",
+ "permit(principal, action == Action::\"call_tool\", resource) when { principal.claim_roles.contains(\"premium\") };",
+ "permit(principal, action == Action::\"call_tool\", resource == Tool::\"calculator\") when { resource.arg_operation == \"add\" || resource.arg_operation == \"subtract\" };"
+ ],
+ "entities_json": "[]"
+ }
+}
+```
+
+You can also define custom resource attributes in `entities_json` for per-tool
+ownership or sensitivity labels.
+
+:::tip
+
+For more policy examples and advanced usage, see
+[Cedar policies](../concepts/cedar-policies.mdx).
+
+:::
diff --git a/versioned_docs/version-1.0/toolhive/_partials/_client-config-intro.mdx b/versioned_docs/version-1.0/toolhive/_partials/_client-config-intro.mdx
new file mode 100644
index 00000000..0d0eeefb
--- /dev/null
+++ b/versioned_docs/version-1.0/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/versioned_docs/version-1.0/toolhive/_partials/_oidc-prerequisites.mdx b/versioned_docs/version-1.0/toolhive/_partials/_oidc-prerequisites.mdx
new file mode 100644
index 00000000..99e1cb66
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/_partials/_oidc-prerequisites.mdx
@@ -0,0 +1,22 @@
+Before you begin, make sure you have:
+
+- ToolHive installed and working
+- Basic familiarity with OAuth, OIDC, and JWT concepts
+- An identity provider that supports OpenID Connect (OIDC), such as Google,
+ GitHub, Microsoft Entra ID (Azure AD), Okta, Auth0, or Kubernetes (for service
+ accounts)
+
+From your identity provider, you'll need:
+
+- Client ID
+- Audience value
+- Issuer URL
+- JWKS URL (for key verification)
+
+ToolHive uses OIDC to connect to your existing identity provider, so you can
+authenticate with your own credentials (for example, Google login) or with
+service account tokens (for example, in Kubernetes). ToolHive never sees your
+password, only signed tokens from your identity provider.
+
+For background on authentication, authorization, and Cedar policy examples, see
+[Authentication and authorization framework](../concepts/auth-framework.mdx).
diff --git a/versioned_docs/version-1.0/toolhive/_partials/_remote-mcp-auth-examples.mdx b/versioned_docs/version-1.0/toolhive/_partials/_remote-mcp-auth-examples.mdx
new file mode 100644
index 00000000..af1b84c6
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/_partials/_remote-mcp-auth-examples.mdx
@@ -0,0 +1,82 @@
+#### Remote MCP server with Auto-Discovered authentication
+
+**Auto-Discovered** authentication is the preferred approach for any MCP server
+that supports it, as ToolHive handles all authentication setup automatically
+with minimal configuration required. Notion's remote MCP server is one example
+that supports this feature:
+
+1. Configuration settings:
+ - **Server name**: `notion-remote`
+ - **Server URL**: `https://mcp.notion.com/mcp`
+ - **Transport**: Streamable HTTP
+ - **Authorization method**: Auto-Discovered
+ - **Callback port**: `45673` (or any available port on your system)
+1. When you install the server, ToolHive discovers the OAuth endpoints,
+ registers a new client, and handles the authentication process.
+1. Your browser opens for authentication. After you authorize access, the remote
+ MCP server appears in your server list with a "Running" status.
+
+#### Remote MCP server with OAuth2 authentication
+
+GitHub's remote MCP server requires manual OAuth configuration. You'll need to
+create a GitHub OAuth app and provide the details in ToolHive.
+
+First, create a GitHub OAuth app:
+
+1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
+1. Click **New OAuth App**
+1. Fill in the application details:
+ - **Application name**: Choose a descriptive name (e.g., "ToolHive GitHub
+ MCP")
+ - **Homepage URL**: Your application's homepage or `http://localhost`
+ - **Authorization callback URL**: `http://localhost:45673/callback` (the port
+ number must match the **Callback port** you will enter in ToolHive)
+1. Click **Register application**
+1. Copy the **Client ID** and generate a **Client secret** for use in ToolHive
+
+Configure the remote MCP server in ToolHive:
+
+1. Configuration settings:
+ - **Server name**: `github-remote`
+ - **Server URL**: `https://api.githubcopilot.com/mcp/`
+ - **Transport**: Streamable HTTP
+ - **Authorization method**: OAuth 2.0
+ - **Callback port**: `45673` (or any available port on your system)
+ - **Authorize URL**: `https://github.com/login/oauth/authorize`
+ - **Token URL**: `https://github.com/login/oauth/access_token`
+ - **Client ID**: Your GitHub OAuth app client ID (e.g.,
+ `Og44jirLIaUgSiTDNGA3`)
+ - **Client secret**: Your GitHub OAuth app client secret (optional if PKCE is
+ enabled)
+ - **Scopes**: `repo,user:email` (comma-separated list of required
+ permissions)
+ - **PKCE**: Enable this option for enhanced security without requiring a
+ client secret
+1. When you install the server, ToolHive opens your browser to authenticate with
+ GitHub and authorize the application.
+1. After you authenticate successfully, the remote MCP server appears in your
+ server list with a "Running" status.
+
+#### Remote MCP server with OIDC authentication
+
+GitHub's remote MCP server also supports OIDC authentication, which provides
+additional security features and standardized token handling. Use the same
+GitHub OAuth app from the previous example.
+
+1. Fill in the configuration form:
+ - **Server name**: `github-remote`
+ - **Server URL**: `https://api.githubcopilot.com/mcp/`
+ - **Transport**: Streamable HTTP
+ - **Authorization method**: OIDC
+ - **Callback port**: `45673` (or any available port on your system)
+ - **Issuer URL**: `https://github.com/login/oauth`
+ - **Client ID**: Your GitHub OAuth app client ID (e.g.,
+ `Og44jirLIaUgSiTDNGA3`)
+ - **Client secret**: Your GitHub OAuth app client secret (optional if PKCE is
+ enabled)
+ - **PKCE**: Enable this option for enhanced security without requiring a
+ client secret
+1. When you install the server, ToolHive opens your browser to authenticate with
+ GitHub using OIDC.
+1. After you authenticate successfully, the remote MCP server appears in your
+ server list with a "Running" status.
diff --git a/versioned_docs/version-1.0/toolhive/concepts/auth-framework.mdx b/versioned_docs/version-1.0/toolhive/concepts/auth-framework.mdx
new file mode 100644
index 00000000..cc8286a8
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/concepts/auth-framework.mdx
@@ -0,0 +1,347 @@
+---
+title: Authentication and authorization
+description: Understanding ToolHive's authentication and authorization framework concepts.
+---
+
+This document explains the concepts behind ToolHive's authentication and
+authorization framework, which secures MCP servers by verifying client identity
+and controlling access to resources. You'll learn how these systems work
+together, the reasoning behind their design, and the benefits of this approach.
+
+:::info[Scope of this documentation]
+
+This documentation covers **client-to-MCP-server authentication**—how clients
+authenticate to the MCP server itself. This is about securing access to the MCP
+server's tools and resources.
+
+This is different from **MCP-server-to-backend authentication**, which involves
+how the MCP server authenticates to external services or APIs it calls (for
+example, a GitHub MCP server authenticating to the GitHub API). That topic is
+covered in [Backend authentication](./backend-auth.mdx).
+
+:::
+
+## Understanding authentication vs. authorization
+
+When you secure MCP servers, you need to understand the strong separation
+between two critical security concepts:
+
+- **Authentication (authN):** Verifying the identity of clients connecting to
+ your MCP server ("Who are you?")
+- **Authorization (authZ):** Determining what actions authenticated clients are
+ allowed to perform ("What can you do?")
+
+You should always perform authentication first, using a trusted identity
+provider, and then apply authorization rules to determine what the authenticated
+identity can do. ToolHive helps you follow this best practice by acting as a
+gateway in front of your MCP servers. This approach lets you use proven identity
+systems for authentication, while keeping your authorization policies clear,
+flexible, and auditable. You don't need to add custom authentication or
+authorization logic to every server—ToolHive handles it for you, consistently
+and securely.
+
+## Why ToolHive centralizes authentication
+
+The
+[official MCP specification](https://modelcontextprotocol.io/docs/tutorials/security/authorization)
+recommends OAuth 2.1-based authorization for HTTP transports, where each MCP
+server acts as an OAuth resource server. In practice, this model creates
+significant operational challenges:
+
+- **OAuth client registration burden:** OAuth 2.0 requires pre-registered
+ redirect URIs at each identity provider. Many providers—such as Google,
+ GitHub, and Atlassian—require manual registration of OAuth clients to obtain a
+ client ID and client secret. If each user client (for example, an IDE) were
+ its own OAuth client, the registration burden would be impractical at scale.
+- **No federation with external services:** While token exchange (RFC 8693) and
+ federated identity providers work when the upstream service is in the same
+ trust domain as the MCP server or has an established trust relationship with
+ the identity provider, many MCP servers need to access external services like
+ GitHub, Google, or Atlassian APIs where no federation relationship exists.
+- **Per-server implementation cost:** Each MCP server would need to implement
+ its own token validation and scope management, duplicating security-critical
+ logic across servers.
+
+ToolHive addresses the per-server implementation cost by centralizing
+authentication and authorization in its proxy layer. You configure ToolHive with
+your identity provider and write Cedar policies for fine-grained
+authorization—individual MCP servers don't need to implement token validation or
+scope management.
+
+The [embedded authorization server](#embedded-authorization-server) addresses
+the remaining challenges. It exposes standard OAuth endpoints and handles the
+full OAuth web flow, eliminating the client registration burden through Dynamic
+Client Registration (DCR) and solving the federation gap by obtaining tokens
+directly from external providers like GitHub or Atlassian. ToolHive delegates
+authentication to the upstream provider and issues its own tokens, giving MCP
+clients a spec-compliant OAuth experience while centralizing the complexity of
+token acquisition and management.
+
+## Authentication framework
+
+ToolHive uses OAuth-based authentication with support for both OAuth 2.1 and
+OpenID Connect (OIDC), enabling both JWT tokens and opaque token validation.
+This lets you connect ToolHive to any OAuth 2.1 or OIDC-compliant identity
+provider (IdP), such as Google, GitHub, Microsoft Entra ID (Azure AD), Okta,
+Auth0, or even Kubernetes service accounts. ToolHive never handles your raw
+passwords or credentials; instead, it relies on access tokens issued by your
+trusted provider—either self-contained JWT tokens or opaque tokens validated
+through token introspection.
+
+### Why use OAuth-based authentication?
+
+OAuth-based authentication provides several key advantages for securing MCP
+servers:
+
+- **Standard and interoperable:** You can connect ToolHive to any OAuth 2.1 or
+ OIDC-compliant IdP without custom code, supporting both human users and
+ automated services.
+- **Proven and secure:** Authentication is delegated to battle-tested identity
+ systems, which handle login UI, multi-factor authentication, and password
+ storage.
+- **Decoupled identity management:** You can use your existing SSO/IdP
+ infrastructure, making onboarding and management seamless.
+- **Flexible for users and services:** This authentication framework supports
+ both interactive user login (for example, Google sign-in) and
+ service-to-service authentication (for example, Kubernetes service account
+ tokens).
+
+### Real-world authentication scenarios
+
+Understanding how OAuth-based authentication works in practice helps you design
+better security for your MCP servers:
+
+**User login via Google:** For example, you can run an MCP server that requires
+authentication using your Google credentials. ToolHive delegates login to
+Google, receives an access token (either a JWT or an opaque token), and
+validates it to authenticate you. This means users get a familiar login
+experience while you benefit from Google's security infrastructure.
+
+**Service-to-service auth with Kubernetes:** If you run a microservice in a
+Kubernetes cluster, it can present its service account token (typically an OIDC
+JWT) to ToolHive. ToolHive validates the token using the cluster's OIDC issuer
+and JWKS endpoint, enabling secure, automated authentication for your internal
+services.
+
+### Token-based authentication
+
+ToolHive supports two types of access tokens for authentication:
+
+**JWT tokens (JSON Web Tokens):** Self-contained tokens that include identity
+information within the token itself. JWTs are validated locally using
+cryptographic signatures and consist of three parts:
+
+1. **Header:** Metadata about the token
+2. **Payload:** Claims about the entity (typically you or your service)
+3. **Signature:** Ensures the token hasn't been altered
+
+**Opaque tokens:** Reference tokens that don't contain identity information
+directly. ToolHive validates these tokens by querying the identity provider's
+token introspection endpoint to retrieve the associated claims.
+
+ToolHive automatically detects the token type and uses the appropriate
+validation method—attempting JWT validation first and falling back to token
+introspection if needed.
+
+### Authentication flow
+
+The authentication process follows these steps:
+
+1. **Token acquisition:** You obtain an access token from your identity
+ provider.
+2. **Token presentation:** You include the token in your requests to ToolHive
+ (typically in the Authorization header).
+3. **Token validation:** ToolHive validates the token using either:
+ - **Local validation:** For JWT tokens, verifying the signature, expiration,
+ and claims using the provider's public keys (JWKS)
+ - **Remote validation:** For opaque tokens, querying the provider's token
+ introspection endpoint to verify the token and retrieve claims
+4. **Identity extraction:** ToolHive extracts your identity information from the
+ validated token claims.
+
+```mermaid
+flowchart TD
+ Client -->|Access Token| ToolHive
+ ToolHive -->|Validate Token| Identity_Provider[Identity Provider]
+ ToolHive -->|Evaluate Cedar Policy| Cedar_Authorizer[Cedar Authorizer]
+ Cedar_Authorizer -->|Permit| MCP_Server
+ Cedar_Authorizer -->|Deny| Denied[403 Forbidden]
+```
+
+### Embedded authorization server
+
+In the standard authentication flow described above, clients obtain tokens
+independently from an external identity provider and present them to ToolHive
+for validation. The embedded authorization server provides an alternative model
+where ToolHive itself acts as an OAuth authorization server, retrieving tokens
+from an upstream identity provider on behalf of clients.
+
+:::note
+
+The embedded authorization server is currently available only for Kubernetes
+deployments using the ToolHive Operator.
+
+:::
+
+From the client's perspective, the embedded authorization server provides a
+standard OAuth 2.0 experience:
+
+1. If the client is not yet registered, it registers via Dynamic Client
+ Registration (DCR), receiving a `client_id` and `client_secret`.
+2. The client is directed to the ToolHive authorization endpoint.
+3. ToolHive redirects the client to the upstream identity provider for
+ authentication (for example, signing in with GitHub or Atlassian).
+4. ToolHive exchanges the authorization code for upstream tokens and issues its
+ own JWT to the client, signed with keys you configure.
+5. The client includes this JWT as a `Bearer` token in the `Authorization`
+ header on subsequent requests.
+
+Behind the scenes, ToolHive stores the upstream tokens and uses them to
+authenticate MCP server requests to external APIs. For the complete flow,
+including token storage and forwarding, see
+[Embedded authorization server](./backend-auth.mdx#embedded-authorization-server).
+
+For Kubernetes setup instructions, see
+[Set up embedded authorization server authentication](../guides-k8s/auth-k8s.mdx#set-up-embedded-authorization-server-authentication).
+
+### Identity providers
+
+ToolHive can integrate with any provider that supports OAuth 2.1 or OIDC,
+including:
+
+- Google
+- GitHub
+- Microsoft Entra ID (Azure AD)
+- Okta
+- Auth0
+- Kubernetes (service account tokens)
+
+These same providers work with both external token validation and the embedded
+authorization server. For the embedded authorization server, the upstream
+provider must support the OAuth 2.0 authorization code flow.
+
+### Token validation methods
+
+ToolHive supports multiple token validation methods to work with different
+identity providers:
+
+- **JWT validation:** For providers that issue JWT tokens, ToolHive validates
+ tokens locally using the provider's JWKS endpoint. This verifies the token's
+ signature, expiration, and claims without calling the identity provider for
+ each request.
+- **Token introspection:** For providers that issue opaque tokens, ToolHive
+ validates tokens by querying the provider's introspection endpoint. This
+ supports RFC 7662 (OAuth 2.0 Token Introspection), Google's tokeninfo API, and
+ GitHub's token validation API.
+
+ToolHive automatically detects the token type—it first attempts JWT validation,
+and if that fails, it falls back to token introspection. This means you don't
+need to configure which validation method to use; ToolHive handles it
+automatically based on the token format.
+
+## Authorization framework
+
+After authentication, ToolHive enforces authorization using Amazon's Cedar
+policy language. ToolHive acts as a gateway in front of MCP servers, handling
+all authorization checks before requests reach the server logic. This means MCP
+servers do not need to implement their own OAuth or custom authorization
+logic—ToolHive centralizes and standardizes access control.
+
+### Why Cedar for authorization?
+
+Cedar provides several advantages for MCP server authorization:
+
+- **Expressive and flexible:** Cedar supports both role-based (RBAC) and
+ attribute-based (ABAC) access control patterns, letting you create policies
+ that match your security requirements.
+- **Formally verified:** Cedar's design has been formally verified for safety
+ and security properties, which reduces the risk of policy bugs.
+- **Human-readable:** Cedar policies use clear, declarative syntax that's easy
+ to read, write, and audit.
+- **Policy enforcement point:** ToolHive blocks unauthorized requests before
+ they reach the MCP server, which reduces risk and simplifies server code.
+- **Secure by default:** Authorization is explicit—if a request is not
+ explicitly permitted, it is denied. Deny rules take precedence over permit
+ rules (deny overrides).
+
+### Authorization components
+
+ToolHive's authorization framework consists of:
+
+1. **Cedar authorizer:** Evaluates Cedar policies to determine if a request is
+ authorized
+2. **Authorization middleware:** Extracts information from MCP requests and uses
+ the Cedar Authorizer
+3. **Configuration:** A JSON or YAML file that specifies the Cedar policies and
+ entities
+
+### Authorization flow
+
+When a request arrives at an MCP server with authorization enabled:
+
+1. The authentication middleware authenticates the client and adds token claims
+ to the request context
+2. The authorization middleware extracts information from the request
+ (principal, action, resource, and any arguments)
+3. The Cedar authorizer evaluates policies to determine if the request is
+ authorized
+4. If authorized, the request proceeds; otherwise, a 403 Forbidden response is
+ returned
+
+```mermaid
+flowchart TD
+ Client -->|Access Token| ToolHive
+ ToolHive -->|Validate Token| Auth_Middleware
+ Auth_Middleware -->|Extract Claims| Authz_Middleware
+ Authz_Middleware -->|Evaluate Cedar Policies| Cedar_Authorizer
+ Cedar_Authorizer -->|Permit| MCP_Server
+ Cedar_Authorizer -->|Deny| Denied[403 Forbidden]
+```
+
+## Security and operational benefits
+
+ToolHive's authentication and authorization approach provides several key
+benefits:
+
+- **Separation of concerns:** Authentication and authorization are handled
+ independently, following security best practices.
+- **Integration with existing systems:** Use your existing identity
+ infrastructure (SSO, IdPs, Kubernetes, etc.).
+- **Centralized, flexible policy model:** Define precise, auditable access rules
+ in a single place—no need to modify MCP server code.
+- **Secure by default:** Requests are denied unless explicitly permitted by
+ policy, with deny precedence for maximum safety.
+- **Auditable and versionable:** Policies are clear, declarative, and can be
+ tracked in version control for compliance and review.
+- **Developer and operator friendly:** ToolHive acts as a smart proxy, so you
+ don't need to implement complex OAuth or custom auth logic in every server.
+
+## Client authentication support
+
+While ToolHive provides a robust authentication and authorization framework for
+MCP servers, authentication support varies across the MCP client ecosystem.
+
+### MCP client capabilities
+
+The MCP ecosystem includes numerous clients with varying levels of
+authentication support. Authentication support is not universal. Some clients
+focus primarily on local, unauthenticated MCP servers for development workflows,
+while others provide enterprise-grade authentication for production deployments.
+
+When selecting an MCP client for authenticated workflows, look for clients that
+support the MCP authentication standards, including OAuth 2.1 and
+transport-level authentication mechanisms.
+
+ToolHive's OIDC-based authentication approach aligns with industry standards and
+works with clients that support modern authentication protocols. As the MCP
+ecosystem continues to mature, we expect authentication support to become more
+standardized across clients.
+
+## Related information
+
+- For configuring the embedded authorization server in Kubernetes, see
+ [Embedded authorization server authentication](../guides-k8s/auth-k8s.mdx#set-up-embedded-authorization-server-authentication)
+- For backend authentication concepts, see
+ [Backend authentication](./backend-auth.mdx)
+- For detailed policy writing guidance, see
+ [Cedar policies](./cedar-policies.mdx)
diff --git a/versioned_docs/version-1.0/toolhive/concepts/backend-auth.mdx b/versioned_docs/version-1.0/toolhive/concepts/backend-auth.mdx
new file mode 100644
index 00000000..04efb279
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/concepts/backend-auth.mdx
@@ -0,0 +1,477 @@
+---
+title: Backend authentication
+description:
+ Understanding how MCP servers authenticate to external services using
+ ToolHive's backend authentication patterns, including static credentials,
+ token exchange, and the embedded authorization server.
+---
+
+This document explains how ToolHive helps MCP servers authenticate to
+third-party APIs and backend services exposed through the MCP servers. You'll
+learn about the backend authentication patterns ToolHive supports, why they
+improve security and multi-tenancy, and how they simplify MCP server
+development.
+
+:::info[Scope of this documentation]
+
+This documentation covers **MCP-server-to-backend authentication**—how MCP
+servers authenticate to external services or APIs they call (for example, a
+GitHub MCP server authenticating to the GitHub API).
+
+This is different from **client-to-MCP-server authentication**, which involves
+how clients authenticate to the MCP server itself. That topic is covered in
+[Authentication and authorization](./auth-framework.mdx).
+
+:::
+
+## The challenge of backend authentication
+
+The MCP specification focuses on authorization to the MCP server but doesn't
+specify how an MCP server should authenticate to the services it exposes. This
+is intentionally left to implementers, which makes sense from a specification
+perspective but leaves MCP server developers without clear guidance.
+
+Many MCP servers today either embed static API keys or require custom
+authentication code. This creates several problems:
+
+- **Security risks:** Long-lived credentials stored in configuration files or
+ environment variables can be compromised
+- **Audit challenges:** When multiple users share a service account, you can't
+ trace individual actions
+- **Multi-tenancy complexity:** Supporting multiple tenants with isolated
+ credentials requires significant custom code
+
+ToolHive addresses these challenges with three backend authentication patterns:
+static credentials for services that don't support OAuth, token exchange for
+services in the same or federated trust domain, and the embedded authorization
+server for OAuth-based external APIs where no federation exists.
+
+## How ToolHive handles backend authentication
+
+ToolHive sits between clients and MCP servers, and can acquire backend
+credentials on behalf of the MCP server. Depending on the pattern, it might
+exchange the client's token, run an OAuth flow against an external provider, or
+inject static credentials. In each case, the MCP server receives ready-to-use
+credentials—via an `Authorization: Bearer` header, another header, or
+environment variables, depending on the pattern—without needing to implement
+custom authentication logic or manage secrets directly.
+
+## Backend authentication patterns
+
+ToolHive supports three patterns for backend authentication. Which one you use
+depends on the relationship between your identity provider (IdP) and the backend
+service.
+
+### Static credentials and API keys
+
+When a backend service requires API keys, database passwords, or other static
+credentials, you can configure them directly in ToolHive as environment
+variables, secret files, or injected headers.
+
+This is the simplest pattern, but it provides the least security and
+auditability. Static credentials are long-lived and shared across all users, so
+there is no per-user attribution in audit logs.
+
+When using static credentials, consider integrating with a secret management
+system like [HashiCorp Vault](../integrations/vault.mdx) for secure storage and
+rotation.
+
+### Token exchange
+
+When the backend service trusts the same IdP as your MCP clients—or federation
+is configured between the two IdPs—ToolHive can exchange the client's token for
+one scoped to the backend service using RFC 8693 token exchange. This preserves
+the user's identity across services and provides short-lived, narrowly scoped
+tokens. Because the trust relationship is pre-configured at the IdP, the
+exchange is transparent to the end user—no consent screen required.
+
+#### Same IdP with token exchange
+
+When both the MCP server and the backend service trust the same IdP, and that
+IdP supports [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693) token
+exchange, ToolHive can exchange the internal token for an external one.
+
+```mermaid
+flowchart LR
+ User[User]
+ IDP[Identity Provider]
+ ToolHive[ToolHive Middleware]
+ MCP[MCP Server]
+ Upstream[Upstream Service]
+
+ User -->|login & receive token| IDP
+ User -->|request with token| ToolHive
+ ToolHive -->|subject_token → exchange| IDP
+ IDP -->|external_token issued| ToolHive
+ ToolHive -->|pass external_token| MCP
+ MCP -->|calls with external_token| Upstream
+ Upstream -->|validates token| IDP
+```
+
+**How it works:**
+
+1. The user authenticates to the MCP client and receives an access token from
+ the IdP
+2. ToolHive's token exchange middleware contacts the IdP, presenting the user's
+ access token
+3. The IdP issues a new access token with different audience and scopes
+4. ToolHive passes this access token to the MCP server
+5. The MCP server uses the access token to call the upstream service
+
+#### Federated IdPs with identity mapping
+
+When the backend service trusts a different IdP, but federation is configured
+between the two IdPs, ToolHive can use the federated identity service to issue
+short-lived tokens. Examples include Google's Security Token Service (STS) for
+Google Cloud services and AWS STS for AWS services—both can issue tokens based
+on your corporate identity.
+
+```mermaid
+flowchart LR
+ User[User]
+ IDP1[IdP A - User Login]
+ ToolHive[ToolHive Middleware]
+ IDP2[IdP B - Federated]
+ MCP[MCP Server]
+ Upstream[Upstream Service]
+
+ User -->|login & receive token_A| IDP1
+ User -->|request with token_A| ToolHive
+ ToolHive -->|submit token_A| IDP2
+ IDP2 -->|issue token_B| ToolHive
+ ToolHive -->|pass token_B| MCP
+ MCP -->|call with token_B| Upstream
+ Upstream -->|validate token_B| IDP2
+```
+
+**How it works:**
+
+1. The user authenticates to their MCP client with a corporate IdP and receives
+ token_A
+2. ToolHive submits token_A to the federated identity service
+3. The federated service maps the identity and issues token_B
+4. ToolHive passes token_B to the MCP server
+5. The MCP server uses token_B to call the upstream service
+
+### Embedded authorization server
+
+When the MCP server needs to call an external API where no federation
+relationship exists—such as GitHub, Google Workspace, or Atlassian APIs—the
+embedded authorization server handles the full OAuth web flow against the
+external provider. The proxy redirects the user to authenticate directly with
+the external service, obtains tokens on behalf of the user, and passes the
+upstream token to the MCP server.
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant Proxy as ToolHive Proxy
+ participant ExtProvider as External Provider
+
+ User->>Proxy: Connect
+ Proxy-->>User: Redirect to login
+ User->>ExtProvider: Authenticate
+ ExtProvider->>Proxy: Authorization code
+ Proxy->>ExtProvider: Exchange code for token
+ ExtProvider->>Proxy: Upstream tokens
+ Proxy->>User: Issue JWT
+```
+
+On subsequent MCP requests, ToolHive uses the JWT to retrieve the stored
+upstream tokens and forward them to the MCP server. For details on this
+mechanism, see [Token storage and forwarding](#token-storage-and-forwarding).
+
+The embedded authorization server runs in-process within the ToolHive proxy—no
+separate infrastructure is needed. It supports Dynamic Client Registration
+(DCR), so MCP clients can register automatically with ToolHive—no manual client
+configuration in ToolHive is required.
+
+:::note
+
+The embedded authorization server is currently available only for Kubernetes
+deployments using the ToolHive Operator.
+
+:::
+
+#### Key characteristics
+
+- **In-process execution:** The authorization server runs within the ToolHive
+ proxy—no separate infrastructure or sidecar containers needed.
+- **Configurable signing keys:** JWTs are signed with keys you provide,
+ supporting key rotation for zero-downtime updates.
+- **Flexible upstream providers:** Supports both OIDC providers (with automatic
+ endpoint discovery) and OAuth 2.0 providers (with explicit endpoint
+ configuration).
+- **Configurable token lifespans:** Access tokens, refresh tokens, and
+ authorization codes have configurable durations with sensible defaults.
+- **Dynamic Client Registration (DCR):** Supports OAuth 2.0 Dynamic Client
+ Registration (RFC 7591), allowing MCP clients to register automatically with
+ ToolHive's authorization server—no manual client registration in ToolHive is
+ required.
+- **Direct upstream redirect:** The embedded authorization server redirects
+ clients directly to the upstream provider for authentication (for example,
+ GitHub or Atlassian).
+- **Single upstream provider:** Currently supports one upstream identity
+ provider per configuration.
+
+:::info[Chained authentication not yet supported]
+
+The embedded authorization server redirects clients directly to the upstream
+provider. This means the upstream provider must be the service whose API the MCP
+server calls. Chained authentication—where a client authenticates with a
+corporate IdP like Okta, which then federates to an external provider like
+GitHub—is not yet supported. If your deployment requires this pattern, consider
+using [token exchange](#same-idp-with-token-exchange) with a federated identity
+provider instead.
+
+:::
+
+#### Token storage and forwarding
+
+The embedded authorization server stores upstream tokens (access tokens, refresh
+tokens, and ID tokens from external providers) in session storage. When the
+OAuth flow completes, the server generates a unique session ID and stores the
+upstream tokens keyed by this ID. The JWT issued to the client contains a `tsid`
+(Token Session ID) claim that references this session.
+
+When a client makes an MCP request with this JWT:
+
+1. The ToolHive proxy validates the JWT signature and extracts the `tsid` claim
+2. It retrieves the upstream tokens from session storage using the `tsid`
+3. The proxy replaces the `Authorization` header with the upstream access token
+4. The request is forwarded to the MCP server with the external provider's token
+
+```mermaid
+sequenceDiagram
+ participant Client
+ participant Proxy as ToolHive Proxy
+ participant Store as Session Storage
+ participant MCP as MCP Server
+ participant API as External API
+
+ Note over Client,Store: Initial OAuth flow
+ Proxy->>Store: Store upstream tokensAuthorization issues
+ +If authenticated clients are denied access: + +1. Make sure your Cedar policies explicitly permit the specific action + (remember, default deny) +2. Check that the principal, action, and resource match what's in your policies + (including case and formatting) +3. Examine any conditions in your policies to ensure they're satisfied (for + example, required JWT claims or tool arguments) +4. Remember that Cedar uses a default deny policy—if no policy explicitly + permits an action, it will be denied + +**Troubleshooting tip:** If access is denied, check that your policies +explicitly permit the action. Cedar uses a default deny model—if no policy +matches, the request is denied. + +keyed by session ID + Proxy-->>Client: Issue JWT with tsid claim + + Note over Client,API: Subsequent MCP requests + Client->>Proxy: MCP request with JWT + Proxy->>Proxy: Validate JWT signature + Proxy->>Store: Look up upstream token
using tsid from JWT + Store-->>Proxy: Return upstream access token + Proxy->>MCP: Forward request with
upstream access token + MCP->>API: Call external API + API-->>MCP: Response + MCP-->>Proxy: Response + Proxy-->>Client: Response +``` + +This mechanism allows MCP servers to call external APIs with the user's actual +credentials from the upstream provider, while the client only needs to manage a +single ToolHive-issued JWT. + +#### Automatic token refresh + +Upstream access tokens have their own expiration, independent of the ToolHive +JWT lifespan. When the stored upstream access token has expired, ToolHive +automatically refreshes it using the stored refresh token before forwarding the +request — your MCP session continues without re-authentication. + +If the refresh token is also expired or has been revoked by the upstream +provider, ToolHive returns a `401` response, prompting you to re-authenticate +through the OAuth flow. + +:::warning[Session storage limitations] + +By default, session storage is in-memory only. Upstream tokens are lost when +pods restart, requiring users to re-authenticate. For production deployments, +configure Redis Sentinel as the storage backend for persistent, highly available +session storage. See +[Configure session storage](../guides-k8s/auth-k8s.mdx#configure-session-storage) +for a quick setup, or the full +[Redis Sentinel session storage](../guides-k8s/redis-session-storage.mdx) +tutorial for an end-to-end walkthrough. + +::: + +For the client-facing OAuth flow, see +[Embedded authorization server](./auth-framework.mdx#embedded-authorization-server). +For Kubernetes setup instructions, see +[Set up embedded authorization server authentication](../guides-k8s/auth-k8s.mdx#set-up-embedded-authorization-server-authentication). + +## Token exchange in depth + +This section provides implementation details for the token exchange patterns +described above. For setup instructions, see +[Configure token exchange](../guides-cli/token-exchange.mdx) (CLI) or +[Configure token exchange in Kubernetes](../guides-k8s/token-exchange-k8s.mdx). + +### Same IdP with token exchange + +The token exchange flow demonstrates how ToolHive transforms user identity +tokens into properly scoped service tokens. + +```mermaid +sequenceDiagram + participant Client + participant ToolHive + participant IDP + participant MCP Server + participant Upstream Service + + Client->>ToolHive: Request with user token + ToolHive->>IDP: Validate token + IDP-->>ToolHive: Token valid + ToolHive->>IDP: Exchange token request + IDP-->>ToolHive: Service token + ToolHive->>MCP Server: Request with service token + MCP Server->>Upstream Service: API call + Upstream Service-->>MCP Server: Response + MCP Server-->>ToolHive: Response + ToolHive-->>Client: Response +``` + +When a client authenticates to ToolHive, it receives a token scoped for the MCP +server: + +```json +{ + "iss": "https://idp.example.com/oauth2/default", + "aud": "mcp-server", + "scp": ["backend-mcp:tools:call", "backend-mcp:tools:list"], + "sub": "user@example.com" +} +``` + +ToolHive's token exchange middleware contacts the IdP and exchanges this token +for one scoped to the backend service: + +```json +{ + "iss": "https://idp.example.com/oauth2/default", + "aud": "backend-server", + "scp": ["backend-api:read"], + "sub": "user@example.com" +} +``` + +Notice how the audience (`aud`) and scopes (`scp`) change while preserving the +user's identity (`sub`). This exchanged token is then injected into the +`Authorization: Bearer` HTTP header and passed to the MCP server. + +### Federated IdPs with identity mapping + +When using federated identity providers, ToolHive can map your corporate +identity to an external service identity. This is particularly useful for +accessing cloud services like Google Cloud Platform. + +The client authenticates with your corporate IdP and receives a token: + +```json +{ + "iss": "https://idp.example.com/oauth2/default", + "aud": "mcp-server", + "sub": "user@example.com", + "email": "user@example.com", + "scp": ["mcp:tools:call", "mcp:tools:list"], + "exp": 1729641600, + "iat": 1729638000 +} +``` + +ToolHive's token exchange middleware calls the external Security Token Service +(STS) endpoint. For Google Cloud, this looks like: + +```http +POST https://sts.googleapis.com/v1/token +Content-Type: application/x-www-form-urlencoded + +grant_type=urn:ietf:params:oauth:grant-type:token-exchange +&audience=//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID +&scope=https://www.googleapis.com/auth/bigquery +&requested_token_type=urn:ietf:params:oauth:token-type:access_token +&subject_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... +&subject_token_type=urn:ietf:params:oauth:token-type:jwt +``` + +The federated service returns a token that maps your corporate identity to a +federated principal: + +```json +{ + "iss": "https://sts.googleapis.com", + "sub": "principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/user@example.com", + "aud": "https://bigquery.googleapis.com/", + "email": "user@example.com", + "scope": "https://www.googleapis.com/auth/bigquery", + "exp": 1729641600, + "iat": 1729638000 +} +``` + +This exchanged token is injected into the `Authorization: Bearer` HTTP header +and passed to the MCP server. The MCP server uses this token to make upstream +API calls, with each request attributed to the individual user's federated +identity rather than a shared service account. + +Federation-based token exchange has several important characteristics that +distinguish it from standard token exchange: + +1. **No client authentication required:** The external STS endpoint doesn't + require `client_id` or `client_secret`. The OAuth JWT itself serves as proof + of identity. +2. **Identity federation pool as intermediary:** The `audience` parameter points + to a federation pool configuration, not directly to the target service. +3. **Principal mapping:** User attributes (email, sub) from the OAuth token are + mapped to federated principals for access control. +4. **Individual audit trail:** Upstream service audit logs show the individual + user identity, not a service account. + +## Security and operational benefits + +ToolHive's token-based authentication patterns (token exchange and the embedded +authorization server) provide several key advantages over static credentials: + +- **Secure:** MCP servers receive short-lived, properly scoped access tokens + instead of embedding long-lived secrets +- **Auditable:** Each API call is attributed to the individual user identity, + making audit trails clear and meaningful +- **Multi-tenant friendly:** Token scoping naturally supports tenant isolation + and separation of duties +- **Developer friendly:** MCP servers don't need custom authentication + logic—they just use the provided token +- **Least privilege:** Tokens are narrowly scoped to specific audiences and + permissions, reducing the blast radius if compromised +- **Consistent:** The same pattern works across different backend services and + identity providers + +## Choosing the right backend authentication pattern + +| Scenario | Pattern | Why | +| ------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------- | +| Backend only accepts API keys or static credentials | [Static credentials](#static-credentials-and-api-keys) | No OAuth support; configure credentials directly in ToolHive | +| Backend trusts the same IdP as your clients | [Token exchange (same IdP)](#same-idp-with-token-exchange) | Exchange the client token for a backend-scoped token via RFC 8693 | +| Backend trusts a federated IdP (for example, Google Cloud) | [Token exchange (federation)](#federated-idps-with-identity-mapping) | Map your corporate identity to the federated service | +| Backend is an external API with no federation (for example, GitHub) | [Embedded authorization server](#embedded-authorization-server) | Run the full OAuth flow against the external provider | + +### Built-in AWS STS support + +For AWS services like the +[AWS MCP Server](https://docs.aws.amazon.com/aws-mcp/), ToolHive has built-in +support for exchanging OIDC tokens for temporary AWS credentials using +`AssumeRoleWithWebIdentity`. This handles the STS exchange and SigV4 request +signing automatically, with claim-based IAM role selection. See the +[AWS STS integration tutorial](../integrations/aws-sts.mdx) for a step-by-step +setup guide. + +## Related information + +- For client authentication concepts, see + [Authentication and authorization](./auth-framework.mdx) +- For the embedded authorization server, see + [Embedded authorization server](./auth-framework.mdx#embedded-authorization-server) +- For configuring the embedded authorization server in Kubernetes, see + [Set up embedded authorization server authentication](../guides-k8s/auth-k8s.mdx#set-up-embedded-authorization-server-authentication) +- For configuring token exchange, see + [Configure token exchange](../guides-cli/token-exchange.mdx) (CLI) or + [Configure token exchange in Kubernetes](../guides-k8s/token-exchange-k8s.mdx) +- For policy configuration, see [Cedar policies](./cedar-policies.mdx) diff --git a/versioned_docs/version-1.0/toolhive/concepts/cedar-policies.mdx b/versioned_docs/version-1.0/toolhive/concepts/cedar-policies.mdx new file mode 100644 index 00000000..ec598b6e --- /dev/null +++ b/versioned_docs/version-1.0/toolhive/concepts/cedar-policies.mdx @@ -0,0 +1,408 @@ +--- +title: Cedar policies +description: Writing and configuring Cedar policies for MCP server authorization. +--- + +This document provides detailed guidance on writing and configuring Cedar +policies for MCP server authorization. You'll learn how to create effective +policies, configure authorization settings, and troubleshoot common issues. + +:::info + +For the conceptual overview of authentication and authorization, see +[Authentication and authorization framework](./auth-framework.mdx). + +::: + +## Cedar policy language + +Cedar policies express authorization rules in a clear, declarative syntax: + +```text +permit|forbid(principal, action, resource) when { conditions }; +``` + +- `permit` or `forbid`: Whether to allow or deny the operation +- `principal`: The entity making the request (the client) +- `action`: The operation being performed +- `resource`: The object being accessed +- `conditions`: Optional conditions that must be satisfied + +## MCP-specific entities + +In the context of MCP servers, Cedar policies use the following entities: + +### Principal + +The client making the request, identified by the `sub` claim in the access +token: + +- Format: `Client::
keyed by session ID + Proxy-->>Client: Issue JWT with tsid claim + + Note over Client,API: Subsequent MCP requests + Client->>Proxy: MCP request with JWT + Proxy->>Proxy: Validate JWT signature + Proxy->>Store: Look up upstream token
using tsid from JWT + Store-->>Proxy: Return upstream access token + Proxy->>MCP: Forward request with
upstream access token + MCP->>API: Call external API + API-->>MCP: Response + MCP-->>Proxy: Response + Proxy-->>Client: Response +``` + +MCP servers receive the upstream access token in the `Authorization: Bearer` +header—they don't need to implement custom authentication logic or manage +secrets. + +## Automatic token refresh + +Upstream access tokens expire independently of the ToolHive JWT lifespan. When +the stored upstream access token has expired, ToolHive automatically refreshes +it using the stored refresh token before forwarding the request. Your MCP +session continues without re-authentication. + +If the refresh token is also expired or has been revoked by the upstream +provider, ToolHive returns a `401` response, prompting re-authentication through +the OAuth flow. + +## Key characteristics + +- **In-process execution:** The authorization server runs within the ToolHive + proxy—no separate infrastructure or sidecar containers needed. +- **Dynamic Client Registration (DCR):** Supports OAuth 2.0 DCR (RFC 7591), + allowing MCP clients to register automatically. No manual client registration + in ToolHive is required. +- **Direct upstream redirect:** Redirects clients directly to the upstream + provider for authentication (for example, GitHub or Atlassian). +- **Configurable signing keys:** JWTs are signed with keys you provide, + supporting key rotation for zero-downtime updates. +- **Flexible upstream providers:** Supports OIDC providers (with automatic + endpoint discovery) and plain OAuth 2.0 providers (with explicit endpoint + configuration). +- **Configurable token lifespans:** Access tokens, refresh tokens, and + authorization codes have configurable durations with sensible defaults. + +## Session storage + +By default, session storage is in-memory. Upstream tokens are lost when pods +restart, requiring users to re-authenticate. + +For production deployments, configure Redis Sentinel as the storage backend for +persistent, highly available session storage. See +[Configure session storage](../guides-k8s/auth-k8s.mdx#configure-session-storage) +for a quick setup, or the full +[Redis Sentinel session storage](../guides-k8s/redis-session-storage.mdx) guide +for an end-to-end walkthrough. + +## MCPServer vs. VirtualMCPServer + +The embedded auth server is available on both `MCPServer` and `VirtualMCPServer` +resources, with some differences: + +| | MCPServer | VirtualMCPServer | +| ---------------------- | ------------------------------------------- | ------------------------------------------------------------------------------ | +| Configuration location | Separate `MCPExternalAuthConfig` resource | Inline `authServerConfig` block on the resource | +| Upstream providers | Single upstream provider | Multiple upstream providers with sequential authorization chaining | +| Token forwarding | Automatic (single provider, single backend) | Explicit `upstreamInject` or `tokenExchange` config maps providers to backends | + +For single-backend deployments on MCPServer, the embedded auth server +automatically swaps the token for each request. For vMCP with multiple backends, +you configure which upstream provider's token goes to which backend using +[upstream token injection](../guides-vmcp/authentication.mdx#upstream-token-injection) +or +[token exchange with upstream tokens](../guides-vmcp/authentication.mdx#token-exchange-with-upstream-tokens). + +## Next steps + +- [Set up embedded authorization server authentication](../guides-k8s/auth-k8s.mdx#set-up-embedded-authorization-server-authentication) + — step-by-step setup for MCPServer resources in Kubernetes +- [vMCP embedded authorization server](../guides-vmcp/authentication.mdx#embedded-authorization-server) + — configuring multiple upstream providers on a VirtualMCPServer +- [Redis Sentinel session storage](../guides-k8s/redis-session-storage.mdx) — + production session storage configuration + +## Related information + +- [Authentication and authorization](./auth-framework.mdx) — client-to-MCP + authentication concepts and the overall framework +- [Backend authentication](./backend-auth.mdx) — all backend authentication + patterns, including when to choose the embedded auth server +- [Cedar policies](./cedar-policies.mdx) — authorization policy configuration diff --git a/versioned_docs/version-1.0/toolhive/concepts/groups.mdx b/versioned_docs/version-1.0/toolhive/concepts/groups.mdx new file mode 100644 index 00000000..1d10e784 --- /dev/null +++ b/versioned_docs/version-1.0/toolhive/concepts/groups.mdx @@ -0,0 +1,161 @@ +--- +title: Organizing MCP servers with groups +sidebar_label: Organizing MCP servers +description: + Understanding when and why to use groups for organizing MCP servers and + controlling client access. +--- + +As your MCP server usage grows, managing multiple servers becomes increasingly +complex. Groups provide a way to organize servers logically and control which +tools are available to different clients. + +## The problem groups solve + +Without groups, all your MCP servers live in a single pool. This creates +challenges: + +- **Tool overload**: AI clients see every tool from every server, making it + harder to select the right one +- **No separation of concerns**: Development tools mix with production tools +- **One-size-fits-all access**: Every client gets access to everything, even + when they only need a subset + +Groups address these issues by letting you organize servers into logical +collections and control which clients can access each collection. + +## When to use groups + +Groups are most valuable when you need to: + +- **Separate environments**: Keep development, staging, and production servers + isolated so you don't accidentally use production tools during development +- **Organize by project**: Give each team access to the tools they need without + cluttering their workspace with irrelevant servers +- **Customize client access**: Configure different AI clients with different + tool sets based on their purpose +- **Reduce context for AI**: Limit the tools available to an AI client so it can + make better decisions about which tool to use + +### When groups aren't necessary + +Groups add organizational overhead, so they're not always the right choice: + +- **Single server setups**: If you're running just one or two MCP servers, + groups don't provide much benefit +- **Universal access needs**: If all clients need access to all servers, a + single default group works fine +- **Simple personal use**: For individual developers with straightforward needs, + the default group is often sufficient + +## Organizational patterns + +Here are common ways teams organize their groups: + +### Environment-based groups + +Separate servers by deployment environment to prevent mixing development and +production contexts: + +| Group | Purpose | +| ----------- | ---------------------------------------------- | +| development | Experimental tools, local databases, test APIs | +| staging | Pre-production testing with realistic data | +| production | Live systems with appropriate access controls | + +This pattern is useful when: + +- You run the same MCP server with different configurations per environment +- You want to prevent accidental production access during development +- Different team members need different environment access + +This pattern works well when: + +- Teams have distinct tool requirements +- You want to reduce clutter in each team's AI client +- Different teams work on different parts of your system + +### Project-based groups + +Create groups for specific projects or products: + +| Group | Servers | +| -------------- | ------------------------------------------- | +| mobile-app | Firebase, app store tools, mobile analytics | +| web-platform | CMS tools, CDN management, web analytics | +| internal-tools | Admin dashboards, reporting tools | + +This approach helps when: + +- Projects have unique tool requirements +- You want focused AI assistance for specific work contexts +- Multiple teams contribute to the same project + +## Groups and client access + +One of the most powerful aspects of groups is controlling which AI clients can +access which servers. When you configure a client for a specific group, that +client only sees servers in that group. + +This matters because: + +- **Better AI performance**: Fewer tools means the AI can make more confident + tool selections +- **Appropriate access**: Different clients can have different capabilities + based on their purpose +- **Reduced noise**: Developers see only the tools relevant to their current + work + +For example, you might configure: + +- **Visual Studio Code** with access to your development group for day-to-day + coding +- **Claude Desktop** with access to your production group for operational tasks +- **GitHub Copilot** with access to a restricted group for code review + +:::tip + +A single client can access multiple groups. This is useful when you need tools +from several areas, like a developer who works across frontend and backend. + +::: + +## Default group behavior + +Every ToolHive installation has a `default` group that cannot be deleted. This +group serves as: + +- **The starting point**: New servers go here unless you specify otherwise +- **The fallback**: Servers move here when their group is deleted +- **The simple path**: If you don't need organization, just use the default + +You don't need to create custom groups to use ToolHive effectively. The default +group works well for simple setups and individual use. + +## Designing your group structure + +When planning your groups, consider: + +1. **Start simple**: Begin with the default group and add custom groups only + when you feel the need for organization +2. **Match your workflow**: Groups should reflect how you actually work, not an + idealized structure +3. **Consider client configuration**: Think about which clients need access to + which servers +4. **Plan for growth**: Choose a pattern that scales as you add more servers + +:::info + +Each server belongs to exactly one group. If you need the same MCP server in +multiple groups (for example, a GitHub server in both development and +production), run separate instances with different names and configurations. + +::: + +## Next steps + +Now that you understand when and why to use groups, you can: + +- [Organize servers into groups (CLI)](../guides-cli/group-management.mdx) +- [Organize servers into groups (UI)](../guides-ui/group-management.mdx) +- [Configure client access](../guides-cli/client-configuration.mdx) diff --git a/versioned_docs/version-1.0/toolhive/concepts/mcp-primer.mdx b/versioned_docs/version-1.0/toolhive/concepts/mcp-primer.mdx new file mode 100644 index 00000000..d3d98330 --- /dev/null +++ b/versioned_docs/version-1.0/toolhive/concepts/mcp-primer.mdx @@ -0,0 +1,72 @@ +--- +title: 'Model Context Protocol (MCP): A friendly primer for builders' +sidebar_label: MCP primer +description: + A brief introduction to the Model Context Protocol (MCP) and its benefits for + developers. +--- + +**TL;DR:** MCP offers a pragmatic, language-friendly bridge between +probabilistic code generators and the real-world systems where your source of +truth lives. It's young, but it already solves pain points around context size, +adapter sprawl, and brittle prompts—thanks largely to an open, welcoming +developer community. If you're building next-gen coding tools, now's the ideal +moment to give MCP a spin and leave your fingerprints on the spec. + +## Why we needed something new + +Modern code-generation models work by guessing the next token from probability +space. By nature they are powerful but probabilistic and work with natural +language. Context drives everything and they can only work on what they can see. +Most real-world context developers use lives outside the model: in GitHub repos, +API docs, RFCs, and issue trackers. Bridging that gap has been messy: + +| Traditional approach | Pain point for GenAI tools | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | +| Custom adapters / plugins per data source | Hard to keep in sync; brittle when schemas change | +| Prompt stuffing (copy-pasting docs into the prompt) | Dilutes effectiveness and reduces response acceptance rates, bloats token budget, hurts latency & cost | +| REST APIs with rigid schemas | Fine for deterministic code, awkward for probabilistic LLMs that prefer natural language | + +MCP tackles these headaches by letting a model **ask external systems for facts +or files using a concise, natural syntax that itself is easy for generative +models to emit and parse.** + +## What problems does MCP solve? + +- **Token-efficient context retrieval** \ + _One-shot, structured queries_ (e.g., + `mcp://github?repo=owner/project\&path=README.md`) let the model fetch exactly + what it needs—no boilerplate, no giant system prompts. +- **Natural-language-friendly envelope** \ + The URI-like syntax is short, deterministic, yet readable enough that an LLM + can generate it without dedicated training. Embeddings created before MCP work + just fine with MCP. +- **Uniform surface over heterogeneous data** \ + Git blobs, Swagger files, Confluence pages, or a private vector store all look + like "resources" under the same scheme. Tool builders write one resolver and + get many back-ends without additional work. +- **Graceful failure semantics** \ + Every MCP response carries both _content_ and a lightweight _provenance_ + object (source, timestamp, hash). Models can decide to retry, ignore, or cite. + +## The emergence of open community + +A community has sprung up around the MCP protocol incredibly quickly. + +The spec is Apache-licensed and refreshingly small, clean, and simple, which +makes the whole thing pretty easy to grok. SDK's abound and thousands of +examples exist. The efforts of communities like golang with the go-mcp release +in April 2025 are moving server development beyond the boundaries of the +traditional JavaScript and Python ecosystems. The Golang portfolio servers +inventory is growing incredibly quickly and with it comes a wealth of production +oriented access to resources. + +There's no governing foundation yet, but a lightweight steering group triages +PRs and publishes version tags. + +## Where MCP is headed + +Expect iterative, community-driven releases—v1.0 is slated for late 2025 with a +stable core and optional capability sets (search, write-back, streaming). The +protocol's youth means rough edges, but that also means **you can still shape +it**: file issues, prototype adapters, or just lurk and learn. diff --git a/versioned_docs/version-1.0/toolhive/concepts/observability.mdx b/versioned_docs/version-1.0/toolhive/concepts/observability.mdx new file mode 100644 index 00000000..f3cb8b26 --- /dev/null +++ b/versioned_docs/version-1.0/toolhive/concepts/observability.mdx @@ -0,0 +1,497 @@ +--- +title: Observability +description: Understanding ToolHive's observability features for MCP server monitoring +--- + +ToolHive provides comprehensive observability for your MCP server interactions +through built-in OpenTelemetry instrumentation. You get complete visibility into +how your MCP servers perform, including detailed traces, metrics, and error +tracking. + +## How telemetry works + +ToolHive automatically instruments your MCP server interactions without +requiring changes to your servers. When you enable telemetry, ToolHive captures +detailed information about every request, tool call, and server interaction. + +ToolHive's telemetry captures rich, protocol-aware information because it +understands MCP operations. You get detailed traces showing tool calls, resource +access, and prompt operations rather than generic HTTP requests. + +## Distributed tracing + +Distributed tracing shows you the complete journey of each request through your +MCP servers. ToolHive creates comprehensive traces that provide end-to-end +visibility across the proxy-container boundary. + +### Trace structure + +Here's what a trace looks like when a client calls a tool in the GitHub MCP +server (some fields omitted for brevity): + +```text +Span: tools/call create_issue (150ms) +├── service.name: thv-github +├── service.version: v0.1.9 +├── http.request.method: POST +├── http.request.body.size: 256 +├── http.response.status_code: 202 +├── http.response.body.size: 1024 +├── url.full: /messages?session_id=b1d22d07-b35f-4260-9c0c-b872f92f64b1 +├── url.path: /messages +├── url.scheme: https +├── server.address: localhost:14972 +├── user_agent.original: claude-code/1.0.53 +├── mcp.method.name: tools/call +├── mcp.server.name: github +├── mcp.session.id: abc123 +├── rpc.system.name: jsonrpc +├── jsonrpc.protocol.version: 2.0 +├── jsonrpc.request.id: 5 +├── gen_ai.tool.name: create_issue +├── gen_ai.operation.name: execute_tool +├── gen_ai.tool.call.arguments: owner=stacklok, repo=toolhive, pullNumber=1131 +├── network.transport: tcp +└── network.protocol.name: http +``` + +### MCP-specific traces + +ToolHive automatically captures traces for all MCP operations, including: + +- **Tool calls** (`tools/call`) - When AI assistants use tools +- **Resource access** (`resources/read`) - When servers read files or data +- **Prompt operations** (`prompts/get`) - When servers retrieve prompts +- **Connection events** (`initialize`) - When clients connect to servers + +### Trace attributes + +Each trace includes detailed context across several layers: + +#### Service information + +```text +service.name: thv-github +service.version: v0.1.9 +host.name: my-machine +``` + +#### HTTP layer + +```text +http.request.method: POST +http.request.body.size: 256 +http.response.status_code: 202 +http.response.body.size: 1024 +url.full: /messages?session_id=b1d22d07-b35f-4260-9c0c-b872f92f64b1 +url.path: /messages +url.scheme: https +url.query: session_id=b1d22d07-b35f-4260-9c0c-b872f92f64b1 +server.address: localhost:14972 +user_agent.original: claude-code/1.0.53 +``` + +#### Network layer + +```text +network.transport: tcp +network.protocol.name: http +network.protocol.version: 1.1 +client.address: 127.0.0.1 +client.port: 52431 +``` + +#### MCP protocol details + +Details about the MCP operation being performed (some fields are specific to +each operation): + +```text +mcp.method.name: tools/call +mcp.server.name: github +mcp.session.id: abc123 +mcp.protocol.version: 2025-03-26 +rpc.system.name: jsonrpc +jsonrpc.protocol.version: 2.0 +jsonrpc.request.id: 123 +``` + +#### Method-specific attributes + +- **`tools/call`** traces include: + - `gen_ai.tool.name` - The name of the tool being called + - `gen_ai.operation.name` - Set to `execute_tool` + - `gen_ai.tool.call.arguments` - Sanitized tool arguments (sensitive values + redacted) + +- **`resources/read`** traces include: + - `mcp.resource.uri` - The URI of the resource being accessed + +- **`prompts/get`** traces include: + - `gen_ai.prompt.name` - The name of the prompt being retrieved + +- **`initialize`** traces include: + - `mcp.client.name` - The name of the connecting client (always emitted) + - `mcp.protocol.version` - The MCP protocol version negotiated + +:::note[Legacy attribute names] + +By default, ToolHive emits both the new OpenTelemetry semantic convention +attribute names shown above and legacy attribute names (e.g., `http.method`, +`mcp.method`, `mcp.tool.name`) for backward compatibility with existing +dashboards. You can control this with the `--otel-use-legacy-attributes` flag. + +::: + +## Metrics collection + +ToolHive automatically collects metrics about your MCP server usage and +performance. These metrics help you understand usage patterns, performance +characteristics, and identify potential issues. + +### Metric labels + +All metrics include consistent labels for filtering and aggregation: + +- `server` - MCP server name (e.g., `fetch`, `github`) +- `transport` - Backend transport type (`stdio`, `sse`, or `streamable-http`) +- `method` - HTTP method (`POST`, `GET`) +- `mcp_method` - MCP protocol method (e.g., `tools/call`, `resources/read`) +- `status` - Request outcome (`success` or `error`) +- `status_code` - HTTP status code (`200`, `400`, `500`) +- `tool` - Tool name for tool-specific metrics + +### Key metrics + +Example metrics from the Prometheus `/metrics` endpoint are shown below (some +fields are omitted for brevity): + +#### Request metrics + +```promql +# HELP toolhive_mcp_requests_total Total number of MCP requests +# TYPE toolhive_mcp_requests_total counter +toolhive_mcp_requests_total{mcp_method="tools/list",method="POST",server="github",status="success",status_code="202",transport="stdio"} 2 + +# HELP toolhive_mcp_request_duration_seconds Duration of MCP requests in seconds +# TYPE toolhive_mcp_request_duration_seconds histogram +toolhive_mcp_request_duration_seconds_bucket{mcp_method="tools/list",method="POST",server="github",status="success",status_code="202",transport="stdio",le="10000"} 2 +toolhive_mcp_request_duration_seconds_bucket{mcp_method="tools/list",method="POST",server="github",status="success",status_code="202",transport="stdio",le="+Inf"} 2 +toolhive_mcp_request_duration_seconds_sum{mcp_method="tools/list",method="POST",server="github",status="success",status_code="202",transport="stdio"} 0.000219416 +toolhive_mcp_request_duration_seconds_count{mcp_method="tools/list",method="POST",server="github",status="success",status_code="202",transport="stdio"} 2 +``` + +#### Connection metrics + +```promql +# HELP toolhive_mcp_active_connections Number of active MCP connections +# TYPE toolhive_mcp_active_connections gauge +toolhive_mcp_active_connections{connection_type="sse",server="github",transport="stdio"} 3 +``` + +#### Tool-specific metrics + +```promql +# HELP toolhive_mcp_tool_calls_total Total number of MCP tool calls +# TYPE toolhive_mcp_tool_calls_total counter +toolhive_mcp_tool_calls_total{server="github",status="success",tool="get_file_contents"} 15 +toolhive_mcp_tool_calls_total{server="github",status="success",tool="list_pull_requests"} 4 +toolhive_mcp_tool_calls_total{server="github",status="success",tool="search_issues"} 2 +``` + +### MCP semantic convention metrics + +In addition to the ToolHive-prefixed metrics above, ToolHive emits metrics that +follow the +[OpenTelemetry MCP semantic conventions](https://github.com/open-telemetry/semantic-conventions): + +| Metric | Type | Description | +| ------------------------------- | --------- | ---------------------------------------- | +| `mcp.server.operation.duration` | Histogram | Duration of MCP server operations | +| `mcp.client.operation.duration` | Histogram | Duration of MCP client operations (vMCP) | + +These metric names follow the OpenTelemetry MCP semantic conventions in OTLP +exports and use the same labels as the ToolHive-prefixed metrics. When exposed +via the Prometheus `/metrics` endpoint, their names are converted to +Prometheus-safe form by replacing dots (`.`) with underscores (`_`): + +- `mcp.server.operation.duration` → `mcp_server_operation_duration` +- `mcp.client.operation.duration` → `mcp_client_operation_duration` + +### vMCP metrics + +When using Virtual MCP Server (vMCP), additional metrics are available for +monitoring backend operations, workflow executions, and optimizer performance. +For details, see the +[vMCP telemetry guide](../guides-vmcp/telemetry-and-metrics.mdx). + +## Trace context propagation + +ToolHive supports two methods of trace context propagation: + +- **HTTP headers**: Standard W3C Trace Context (`traceparent` and `tracestate` + headers) and W3C Baggage propagation +- **MCP `_meta` field**: Trace context embedded in MCP request parameters via + the `params._meta` field, following the MCP specification + +When both are present, the MCP `_meta` trace context takes priority. This +enables proper trace correlation across MCP server boundaries, even when MCP +clients inject trace context into the request payload rather than HTTP headers. + +## Export options + +ToolHive supports multiple export formats to integrate with your existing +observability infrastructure. + +### OTLP export + +ToolHive supports OpenTelemetry Protocol (OTLP) export for both traces and +metrics to any compatible backend, either directly or via a collector +application. + +The [OpenTelemetry ecosystem](https://opentelemetry.io/ecosystem/vendors/) +includes a wide range of observability backends including open source solutions +like Jaeger, self-hosted solutions like Splunk, and SaaS solutions like Datadog, +New Relic, and Honeycomb. + +### Prometheus export + +ToolHive can expose Prometheus-style metrics at a `/metrics` endpoint, enabling: + +- **Direct scraping** by Prometheus servers +- **Service discovery** in Kubernetes environments +- **Integration** with existing Prometheus-based monitoring stacks + +### Dual export + +Both OTLP and Prometheus can be enabled simultaneously, allowing you to: + +- Send traces to specialized tracing backends +- Expose metrics for Prometheus scraping +- Maintain compatibility with existing monitoring infrastructure + +## Data sanitization + +ToolHive automatically protects sensitive information in traces: + +- **Sensitive arguments**: Tool arguments containing passwords, tokens, or keys + are redacted +- **Sensitive key detection**: Arguments with keys containing patterns like + "password", "token", "secret", "key", "auth", or "credential" are redacted +- **Argument truncation**: Long arguments are truncated to prevent excessive + trace size + +For example, a tool call with sensitive arguments: + +```text +gen_ai.tool.call.arguments: password=secret123, api_key=abc456, title=Bug report +``` + +ToolHive sanitizes this in the trace as: + +```text +gen_ai.tool.call.arguments: password=[REDACTED], api_key=[REDACTED], title=Bug report +``` + +## Monitoring examples + +These examples show how ToolHive's observability works in practice. + +### Tool call monitoring + +When a client calls the `create_issue` tool: + +**Request**: + +```json +{ + "jsonrpc": "2.0", + "id": "req_456", + "method": "tools/call", + "params": { + "name": "create_issue", + "arguments": { + "title": "Bug report", + "body": "Found an issue with the API" + } + } +} +``` + +**Generated trace**: + +```text +Span: tools/call create_issue +├── mcp.method.name: tools/call +├── jsonrpc.request.id: req_456 +├── gen_ai.tool.name: create_issue +├── gen_ai.tool.call.arguments: title=Bug report, body=Found an issue with... +├── mcp.server.name: github +├── network.transport: tcp +├── http.request.method: POST +├── http.response.status_code: 200 +└── duration: 850ms +``` + +**Generated metrics**: + +```promql +toolhive_mcp_requests_total{mcp_method="tools/call",server="github",status="success"} 1 +toolhive_mcp_request_duration_seconds{mcp_method="tools/call",server="github"} 0.85 +toolhive_mcp_tool_calls_total{server="github",tool="create_issue",status="success"} 1 +``` + +### Error tracking + +Failed requests generate error traces and metrics: + +**Error trace**: + +```text +Span: tools/call invalid_tool +├── mcp.method.name: tools/call +├── gen_ai.tool.name: invalid_tool +├── http.response.status_code: 400 +├── span.status: ERROR +├── span.status_message: Tool not found +└── duration: 12ms +``` + +**Error metrics**: + +```promql +toolhive_mcp_requests_total{mcp_method="tools/call",server="github",status="error",status_code="400"} 1 +toolhive_mcp_tool_calls_total{server="github",tool="invalid_tool",status="error"} 1 +``` + +## Key performance indicators + +Monitor these key metrics for optimal MCP server performance: + +1. **Request rate**: `rate(toolhive_mcp_requests_total[5m])` +2. **Error rate**: `rate(toolhive_mcp_requests_total{status="error"}[5m])` +3. **Response time**: + `histogram_quantile(0.95, toolhive_mcp_request_duration_seconds_bucket)` +4. **Active connections**: `toolhive_mcp_active_connections` + +## Setting up dashboards and alerts + +This section shows practical examples of integrating ToolHive's observability +data with common monitoring tools. + +### Prometheus integration + +Configure Prometheus to scrape ToolHive metrics: + +```yaml title="prometheus.yml" +scrape_configs: + - job_name: 'toolhive-mcp-proxy' + static_configs: + - targets: [ + 'localhost:43832', # Example MCP server + 'localhost:51712' # Example MCP server + ] + scrape_interval: 15s + metrics_path: /metrics +``` + +### Grafana dashboard queries + +Example queries for monitoring dashboards: + +```promql +# Request rate by server +sum(rate(toolhive_mcp_requests_total[5m])) by (server) + +# Error rate percentage +sum(rate(toolhive_mcp_requests_total{status="error"}[5m])) by (server) / +sum(rate(toolhive_mcp_requests_total[5m])) by (server) * 100 + +# Response time percentiles +histogram_quantile(0.95, sum(rate(toolhive_mcp_request_duration_seconds_bucket[5m])) by (le, server)) + +# Tool usage distribution +sum(rate(toolhive_mcp_tool_calls_total[5m])) by (tool, server) + +# Active connections +toolhive_mcp_active_connections +``` + +### Alerting rules + +Example Prometheus alerting rules: + +```yaml title="prometheus.yml" +groups: + - name: toolhive-mcp-proxy + rules: + - alert: HighErrorRate + expr: rate(toolhive_mcp_requests_total{status="error"}[5m]) > 0.1 + for: 2m + labels: + severity: warning + annotations: + summary: 'High error rate in MCP proxy' + description: 'Error rate is {{ $value }} errors per second' + + - alert: HighResponseTime + expr: + histogram_quantile(0.95, toolhive_mcp_request_duration_seconds_bucket) + > 2.0 + for: 5m + labels: + severity: warning + annotations: + summary: 'High response time in MCP proxy' + description: '95th percentile response time is {{ $value }}s' + + - alert: ProxyDown + expr: up{job="toolhive-mcp-proxy"} == 0 + for: 1m + labels: + severity: critical + annotations: + summary: 'MCP proxy is down' + description: 'ToolHive MCP proxy has been down for more than 1 minute' +``` + +## Recommendations + +### Production deployment + +1. Use appropriate sampling rates (1-10% for high-traffic systems) +2. Configure authentication for OTLP endpoints +3. Use HTTPS transport in production +4. Monitor telemetry overhead with metrics +5. Set up alerting on key performance indicators + +### Development and testing + +1. Use 100% sampling for complete visibility +2. Enable local backends (Jaeger, Prometheus) +3. Test with realistic workloads to validate metrics +4. Verify trace correlation across service boundaries + +### Cost optimization + +1. Tune sampling rates based on traffic patterns +2. Use head-based sampling for consistent trace collection +3. Monitor backend costs and adjust accordingly +4. Filter out health check requests if not needed + +## Next steps + +Now that you understand how ToolHive's observability works, you can: + +1. **Choose a monitoring backend** that fits your needs and budget +2. **Follow the tutorial** to set up a local observability stack with + [OpenTelemetry, Jaeger, Prometheus, and Grafana](../integrations/opentelemetry.mdx) +3. **Enable telemetry** when running your servers: + - [using the ToolHive CLI](../guides-cli/telemetry-and-metrics.mdx) + - [using the Kubernetes operator](../guides-k8s/telemetry-and-metrics.mdx) +4. **Set up basic dashboards** to track request rates, error rates, and response + times +5. **Configure alerts** for critical issues + +The telemetry system works automatically once enabled, providing immediate +insights into your MCP server performance and usage patterns. diff --git a/versioned_docs/version-1.0/toolhive/concepts/registry-criteria.mdx b/versioned_docs/version-1.0/toolhive/concepts/registry-criteria.mdx new file mode 100644 index 00000000..ca51933f --- /dev/null +++ b/versioned_docs/version-1.0/toolhive/concepts/registry-criteria.mdx @@ -0,0 +1,166 @@ +--- +title: 'Registry criteria' +description: Criteria for adding MCP servers to the ToolHive registry +--- + +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. + +## Contribute to the registry + +If you have an MCP server that you'd like to add to the ToolHive registry, you +can +[open an issue](https://github.com/stacklok/toolhive-catalog/issues/new?template=add-an-mcp-server.md) +or submit a pull request to the +[toolhive-catalog](https://github.com/stacklok/toolhive-catalog) repository. The +ToolHive team will review your submission and consider adding it to the +registry. + +Criteria for adding an MCP server to the ToolHive registry are outlined below. +These criteria ensure that the servers in the registry meet the standards of +security, quality, and usability that ToolHive aims to uphold. + +Registry entries are defined in the +[toolhive-catalog](https://github.com/stacklok/toolhive-catalog) repository. + +## Criteria for MCP servers + +### Open source requirements + +- Must be fully open source with no exceptions +- Source code must be publicly accessible +- Must use an acceptable open source license (see + [Acceptable licenses](#acceptable-licenses)) + +### Security + +- Software provenance verification (Sigstore, GitHub Attestations) +- SLSA compliance level assessment +- Pinned dependencies and GitHub Actions +- Published Software Bill of Materials (SBOMs) + +### Continuous integration + +- Automated dependency updates (Dependabot, Renovate, etc.) +- Automated security scanning +- CVE monitoring +- Code linting and quality checks + +### Repository metrics + +- Repository stars and forks +- Commit frequency and recency +- Contributor activity +- Issue and pull request statistics + +### API compliance + +- Full MCP API specification support +- Implementation of all required endpoints (tools, resources, etc.) +- Protocol version compatibility + +### Tool stability + +- Version consistency +- Breaking change frequency +- Backward compatibility maintenance + +### Code quality + +- Presence of automated tests +- Test coverage percentage +- Quality CI/CD implementation +- Code review practices + +### Documentation + +- Basic project documentation +- API documentation +- Deployment and operation guides +- Regular documentation updates + +### Release process + +- Established CI-based release process +- Regular release cadence +- Semantic versioning compliance +- Maintained changelog + +### Community health + +#### Responsiveness + +- Active maintainer engagement +- Regular commit activity +- Timely issue and pull request responses (issues open 3-4 weeks without + response is a red flag) +- Bug resolution rate +- User support quality + +#### Community strength + +- Project backing (individual vs. organizational) +- Number of active maintainers +- Contributor diversity +- Corporate or foundation support +- Governance model maturity + +### Security requirements + +#### Authentication and authorization + +- Secure authentication mechanisms +- Proper authorization controls +- Standard security protocol support (OAuth, TLS) + +#### Data protection + +- Encryption for data in transit and at rest +- Proper sensitive information handling + +#### Security practices + +- Clear incident response channels +- Security issue reporting mechanisms (email, GHSA, etc.) + +## Future considerations + +### Automated vs manual checks + +- Balance between automated checks (e.g., CI/CD, security scans) and manual + reviews (e.g., community health, documentation quality) +- Automated checks for basic compliance (e.g., license, API support) +- Manual reviews for nuanced aspects (e.g., community strength, documentation + quality) + +### Scoring system + +- **Required**: Essential attributes (significant penalty if missing) +- **Expected**: Typical well-executed project attributes (moderate score impact) +- **Recommended**: Good practice indicators (positive contribution) +- **Bonus**: Excellence demonstrators (pure positive, no penalty for absence) + +### Tiered classifications + +- "Verified" vs "Experimental/Community" designations +- Minimum threshold requirements (stars, maintainers, community indicators) +- Regular re-evaluation frequency for automated checks + +## Acceptable licenses + +The following open source licenses are accepted for MCP servers in the ToolHive +registry: + +### Permissive licenses + +Licenses such as Apache-2.0, MIT, BSD-2-Clause, and BSD-3-Clause allow maximum +flexibility for integration, modification, and redistribution with minimal +restrictions, making MCP servers accessible across all project types and +commercial applications. + +### Excluded licenses + +We exclude copyleft and restrictive licenses such as AGPL, GPL2, and GPL3 to +ensure MCP servers can be freely integrated into various commercial and open +source projects without legal complications or viral licensing requirements. diff --git a/versioned_docs/version-1.0/toolhive/concepts/skills.mdx b/versioned_docs/version-1.0/toolhive/concepts/skills.mdx new file mode 100644 index 00000000..2149c2bd --- /dev/null +++ b/versioned_docs/version-1.0/toolhive/concepts/skills.mdx @@ -0,0 +1,113 @@ +--- +title: Understanding skills +description: + Learn what skills are in ToolHive, why they exist, and how they relate to MCP + servers. +--- + +A **skill** is a reusable, versioned bundle of instructions, prompts, and +configuration that teaches an AI agent how to perform a specific task. If MCP +servers provide **tools** (the raw capabilities an agent can call), skills +provide the **knowledge** of when, why, and how to use those tools effectively. + +## When you would use skills + +Consider these scenarios: + +- **You maintain a shared MCP registry** and want teams to publish reusable + prompt bundles alongside the MCP servers they connect to, so that other + engineers can discover both the tooling and the expertise in one place. +- **You build internal developer tools** and want to package a "code review" + workflow that combines multiple MCP server calls with domain-specific + instructions, then distribute it through a central catalog. +- **You run a platform team** and want to curate a set of approved skills that + your organization's AI agents can use, with clear versioning and status + tracking. + +## How skills relate to MCP servers + +MCP servers expose tools; skills consume them. A skill might reference one or +more tools from one or more MCP servers, wrapping them in a higher-level +workflow with context-specific instructions. + +```mermaid +flowchart LR + Skill["Skill\n(workflow + prompts)"] -->|references| MCP["MCP Server(s)\n(raw tools)"] +``` + +Skills are stored in the same Registry server instance as MCP servers, but under +a separate extensions API path (`/{registryName}/v0.1/x/dev.toolhive/skills`, +where `{registryName}` is the name of your registry). They are not intermixed +with MCP server entries. + +## Skill structure + +Each skill has the following core fields: + +| Field | Required | Description | +| ------------- | -------- | ------------------------------------------------------------------- | +| `namespace` | Yes | Reverse-DNS identifier (e.g., `io.github.acme`) | +| `name` | Yes | Skill identifier in kebab-case (e.g., `code-review`) | +| `description` | Yes | Human-readable summary of what the skill does | +| `version` | Yes | Semantic version or commit hash (e.g., `1.0.0`) | +| `status` | No | One of `ACTIVE`, `DEPRECATED`, or `ARCHIVED` (defaults to `ACTIVE`) | +| `title` | No | Human-friendly display name | +| `license` | No | SPDX license identifier (e.g., `Apache-2.0`) | + +Skills also support optional fields for packages (OCI or Git references), icons, +repository metadata, allowed tools, compatibility requirements, and arbitrary +metadata. + +### Naming conventions + +- **Namespace**: Use reverse-DNS notation. For example, `io.github.your-org` or + `com.example.team`. This prevents naming collisions across organizations. +- **Name**: Use kebab-case identifiers. For example, `code-review`, + `deploy-checker`, `security-scan`. +- **Version**: Use semantic versioning (e.g., `1.0.0`, `2.1.3`) or a commit + hash. The registry tracks a "latest" pointer per namespace/name pair. + +**Valid examples:** + +- `io.github.acme/code-review` version `1.0.0` +- `com.example.platform/deploy-checker` version `0.3.1` + +**Invalid examples:** + +- `acme/Code Review` (namespace must be reverse-DNS, name must be kebab-case) +- Empty namespace or name (both are required) + +### Package types + +Skills can reference distribution packages in two formats: + +- **OCI**: Container registry references with an identifier, digest, and media + type +- **Git**: Repository references with a URL, ref, commit, and optional subfolder + +## Versioning + +The registry stores multiple versions of each skill and maintains a "latest" +pointer. When you publish a new version, the registry automatically updates the +latest pointer if the new version is newer than the current latest. Publishing +an older version does not change the latest pointer. + +You can retrieve a specific version or request `latest` to get the most recent +one. + +## Current status and what's next + +The skills API is available as an extension endpoint on the Registry server +(`/{registryName}/v0.1/x/dev.toolhive/skills`). You can publish, list, search, +retrieve, and delete skills through this API. + +Skill installation via agent clients (such as the ToolHive CLI or IDE +extensions) is planned for a future release. For now, the registry serves as a +discovery and distribution layer where you can browse available skills and +retrieve their package references. + +## Next steps + +- [Manage skills](../guides-registry/skills.mdx) through the Registry server API +- [Registry server introduction](../guides-registry/intro.mdx) for an overview + of the Registry server diff --git a/versioned_docs/version-1.0/toolhive/concepts/tool-optimization.mdx b/versioned_docs/version-1.0/toolhive/concepts/tool-optimization.mdx new file mode 100644 index 00000000..35b5c85b --- /dev/null +++ b/versioned_docs/version-1.0/toolhive/concepts/tool-optimization.mdx @@ -0,0 +1,260 @@ +--- +title: Optimizing LLM context with tool filtering and overrides +sidebar_label: Optimizing LLM context +description: + Understanding when and why to use tool filtering and overrides to reduce + context pollution and improve AI performance. +--- + +When AI assistants interact with MCP servers, they receive information about +every available tool. While having many tools provides flexibility, it can also +create problems. This guide explains how tool filtering and overrides help you +optimize your AI's context window for better performance and more focused +results. + +## The context pollution problem + +Modern AI clients work by analyzing all available tools and selecting the most +appropriate one for each task. This selection process happens in the AI model's +context, which means every tool's name, description, and schema consumes tokens +and processing time. + +Consider what happens when you connect an AI client to multiple MCP servers: + +- A GitHub server might expose 30+ tools for repositories, issues, pull + requests, and more +- A filesystem server adds another 10+ tools for file operations +- A database server contributes 20+ tools for queries and schema management +- Additional servers for Slack, Jira, monitoring systems, and other integrations + +Before you know it, your AI client is evaluating 100+ tools for every request. + +### Why this matters + +When your AI receives too many tools, several problems emerge: + +**Performance degradation**: More tools mean longer processing time as the AI +model evaluates each option. Tool selection becomes a bottleneck, especially for +complex queries. + +**Higher costs**: Every tool description consumes tokens. In token-based pricing +models, exposing unnecessary tools directly increases your costs for every AI +interaction. + +**Reduced accuracy**: When faced with many similar tools, AI models sometimes +choose incorrectly. A client might use a production database tool when it should +use a development one, or select a write operation when a read would suffice. + +The solution is selective tool exposure - showing your AI only the tools it +actually needs. + +## Tool filtering + +Tool filtering restricts which tools from an MCP server are available to +clients. Think of it as creating a curated subset of functionality for specific +use cases. + +### How filtering works + +ToolHive uses an allow-list approach. When you specify a filter, only the tools +you explicitly list become available. The filtering happens at the HTTP proxy +level, so: + +- The AI only sees allowed tools in its tool list +- Attempts to call filtered tools result in errors +- The backend MCP server remains unchanged + +An empty filter means all tools are available. Once you add any tool to the +filter, only listed tools are exposed. + +### When to use filtering + +Filtering makes sense in several scenarios: + +#### Improving AI tool selection + +When an MCP server exposes many tools but you only need a subset, filtering +improves the AI's ability to choose correctly. For example, enable only pull +request tools from the GitHub server when doing code review, or limit a file +system server to just `read_file` and `list_directory` for a documentation +assistant. Removing irrelevant options helps the AI make more confident +selections. + +#### Limiting access to safe operations + +An MCP server for database access might include both read and write operations. +During development or analysis, you might want to expose only read operations +like `query` and `list_tables`, while filtering out write operations like +`insert`, `update`, and `delete` that modify data or perform destructive +operations. + +#### Creating role-specific tool sets + +Different team members need different capabilities. Junior developers might get +filtered access to safe operations, while senior developers see the full tool +set. Security-sensitive tools like deployment commands might be filtered for +most users but available to DevOps engineers. + +#### Compliance and governance + +When organizational policies restrict certain operations, you can enforce policy +by only exposing approved tools, even if the underlying MCP server provides more +capabilities. + +## Tool overrides + +Tool overrides let you rename tools and update their descriptions without +modifying the backend MCP server. This is particularly valuable when tool names +are unclear or when combining multiple servers. + +### How overrides work + +Overrides maintain a bidirectional mapping between original and user-facing +names. When your AI sees the tool list, it receives the overridden names and +descriptions. When it calls a tool, ToolHive translates the user-facing name +back to the original name for the backend server. + +You can override either the name, the description, or both for each tool. + +### When to use overrides + +Overrides solve several common problems: + +#### Preventing name conflicts + +When combining multiple MCP servers through Virtual MCP Server or running +similar servers for different purposes, naming conflicts are common. Both GitHub +and Jira might have a `create_issue` tool. Overriding these to +`github_create_issue` and `jira_create_issue` eliminates ambiguity. + +When you run the same MCP server multiple times with different configurations, +tool names become identical. For example, running the GitHub server twice (once +for your company's organization and once for open source contributions) requires +renaming tools to `github_company_create_pr` and `github_oss_create_pr` to make +the distinction clear. + +#### Adding context and clarity + +Tool names and descriptions can be improved to provide environment-specific or +use-case-specific information. Renaming `deploy` to `deploy_to_staging` versus +`deploy_to_production` makes the destination explicit and reduces mistakes. +Similarly, you can update descriptions from generic text like "Deploy +application" to specific guidance like "Deploy to staging environment - +auto-rollback enabled." + +## Combining filters and overrides + +Filtering and overrides work together, but understanding their interaction is +important: **filters apply to user-facing names after overrides**. + +This means when you override a tool name, you must use the new name in your +filter list, not the original name. + +### Pattern: Secure subset with clear names + +Start by overriding technical names to be more intuitive, then filter to only +safe operations. + +```json +{ + "toolsOverride": { + "exec_raw_sql": { + "name": "run_database_query", + "description": "Execute read-only SQL queries against the staging database" + }, + "write_table": { + "name": "update_database", + "description": "Modify staging database tables (use with caution)" + } + } +} +``` + +Then filter using the new names: + +```bash +thv run --tools-override overrides.json --tools run_database_query my-db-server +``` + +**Why this works**: Clear names guide the AI while filtering enforces safety by +making destructive operations unavailable. + +### Pattern: Environment-specific configurations + +Different environments need different tool access. In development, you might +expose many tools for flexibility. In production, filter to essential tools +only. + +Your development configuration could expose all tools with friendly names +through overrides. Your production configuration uses the same overrides for +consistency but adds strict filtering to expose only read and monitoring tools, +blocking any write or deployment operations. + +**Why this works**: Consistent naming across environments with +environment-specific filtering prevents accidents while maintaining flexibility. + +### Pattern: Multi-server aggregation + +When using [Virtual MCP Server](vmcp.mdx) to combine multiple MCP servers, +overrides prevent conflicts and improve clarity: + +```json +{ + "toolsOverride": { + "search": { + "name": "github_search", + "description": "Search GitHub repositories and code" + } + } +} +``` + +You can override the `search` tool from different servers to `github_search`, +`jira_search`, and `confluence_search`. Then filter each server to its relevant +tools, creating a clean, conflict-free tool set. + +**Why this works**: Prefixes eliminate ambiguity about which server a tool +targets, while filtering prevents context overload from aggregating many +services. + +## Trade-offs to consider + +While these optimization features provide significant benefits, they also +introduce complexity: + +**Configuration and maintenance overhead**: Filters and overrides require +ongoing maintenance. When MCP servers update their tools, you'll need to adjust +your configurations. When using both features together, remember that filters +apply to overridden names, not original names. + +**Flexibility vs. safety**: Aggressive filtering makes it harder to access tools +you occasionally need. You may find yourself creating exceptions or +reconfiguring access. The more you optimize, the less flexible your system +becomes. + +**Discovery and documentation**: When tools are filtered or renamed, team +members may not realize what capabilities exist. Clear documentation becomes +essential when your visible tools don't match what the MCP server actually +provides. + +Start simple and add complexity only where it provides clear value. + +## Best practices + +**Start minimal**: Begin with a focused tool set and expand as you discover +needs, rather than filtering down from everything. + +**Be specific**: When overriding names and descriptions, provide clear, +context-specific information that helps the AI understand when to use each tool. + +## Related information + +Now that you understand when and why to use tool filtering and overrides, learn +how to configure them: + +- [Customize tools (CLI)](../guides-cli/run-mcp-servers.mdx) +- [Customize tools (UI)](../guides-ui/customize-tools.mdx) +- [Customize tools (Kubernetes)](../guides-k8s/customize-tools.mdx) +- [MCPToolConfig CRD reference](../reference/crd-spec.md) +- [Virtual MCP Server tool aggregation](../guides-vmcp/tool-aggregation.mdx) +- [Optimize tool discovery in vMCP](../guides-vmcp/optimizer.mdx) diff --git a/versioned_docs/version-1.0/toolhive/concepts/vmcp.mdx b/versioned_docs/version-1.0/toolhive/concepts/vmcp.mdx new file mode 100644 index 00000000..ff6bff74 --- /dev/null +++ b/versioned_docs/version-1.0/toolhive/concepts/vmcp.mdx @@ -0,0 +1,170 @@ +--- +title: Understanding Virtual MCP Server +sidebar_label: Virtual MCP Server (vMCP) +description: Learn what Virtual MCP Server does, why it exists, and when to use it. +--- + +This document explains Virtual MCP Server (vMCP), a feature of the ToolHive +Kubernetes Operator. You'll learn why it exists, when to use it, and how it +simplifies managing multiple MCP servers while enabling powerful multi-system +workflows. + +## The problem vMCP solves + +**Before vMCP**: Engineers manage 10+ separate MCP server connections, each with +its own authentication, manually coordinate multi-step workflows across systems, +and repeatedly configure the same parameters. + +**With vMCP**: Connect once to a unified endpoint that aggregates all backend +MCP servers, execute complex multi-system workflows declaratively, and use +pre-configured tools with sensible defaults. + +## Core value propositions + +vMCP delivers four key benefits: + +1. **Reduce complexity**: Many connections become one, dramatically simplifying + configuration +2. **Speed up workflows**: Parallel execution across systems instead of + sequential calls +3. **Improve security**: Centralized authentication and authorization with a + two-boundary model +4. **Enable reusability**: Define workflows once, use them everywhere +5. **Optimize tool discovery**: Reduce token usage by replacing all tool + definitions with two lightweight search-and-call primitives + +## Key capabilities + +### Multi-server aggregation + +Managing 10-20+ MCP server connections is overwhelming. Each server needs its +own configuration, authentication, and maintenance. vMCP aggregates all backend +MCP servers into one endpoint with automatic conflict resolution. + +vMCP supports two types of backends: + +- **MCPServer**: Container-based MCP servers running in your Kubernetes cluster +- **MCPRemoteProxy**: Proxies to external remote MCP servers (SaaS platforms, + third-party services, or MCP servers hosted outside your cluster) + +:::note[MCPRemoteProxy support] + +MCPRemoteProxy support in vMCP is currently in development. vMCP can discover +MCPRemoteProxy backends, but authentication between vMCP and MCPRemoteProxy is +not yet fully implemented. MCPServer backends work fully with vMCP. + +::: + +This architecture enables combining internal tools with external SaaS MCP +endpoints in a single unified interface. + +**Example scenario**: An engineering team needs access to 8 backend servers +(GitHub, Jira, Slack, Confluence, PagerDuty, Datadog, AWS, and internal company +docs). Some are container-based MCPServer resources running in the cluster, +while others are remote SaaS MCP endpoints accessed via MCPRemoteProxy. Instead +of configuring 8 separate connections, they configure one vMCP connection with +SSO. This significantly reduces configuration complexity and makes onboarding +new team members much easier. + +When multiple backend MCP servers have tools with the same name (for example, +both GitHub and Jira have `create_issue`), vMCP automatically prefixes them: +`github_create_issue`, `jira_create_issue`. You can also define custom names for +clarity. + +### Multi-step workflows (composition) + +Real-world tasks span multiple systems and require manual orchestration. vMCP +lets you define declarative workflows with parallel execution, conditionals, +error handling, and human-in-the-loop approval gates. + +**Example scenario**: During an incident investigation, you need logs from your +logging system, metrics from your monitoring platform, traces from your tracing +service, and infrastructure status from your cloud provider. Without vMCP, an +engineer manually runs 4 commands sequentially and aggregates results. With +vMCP, you fetch all of this in parallel, automatically aggregate it into a +formatted report, and create a Jira ticket with all the data. This workflow is +reusable for every incident. + +**Example scenario**: For an app deployment, merge the pull request, wait for +tests, ask a human for approval, deploy only if approved, and notify the team in +Slack. vMCP handles this entire flow declaratively, with automatic rollback on +deployment failure. + +### Tool customization and overrides + +Third-party MCP servers often have generic names, descriptions, and unrestricted +parameters. vMCP lets you filter, rename, and wrap tools without modifying the +upstream servers. + +**Security policy enforcement**: You can restrict a fetch tool to internal +domains only (`*.company.com`), validate URLs before calling the backend, and +provide clear error messages for policy violations. + +**Simplified interfaces**: A complex tool like AWS EC2 might have 20+ +parameters, but your frontend team only needs 3. You can create a simplified +wrapper that uses instance names instead of IDs and pre-fills safe defaults for +all other parameters. + +### Parameter defaults and pre-configuration + +Generic servers require repetitive parameter specification. You always use the +same repo, channel, or database. vMCP lets you create specialized instances with +pre-configured defaults. + +**Example scenario**: Without vMCP, every GitHub query requires specifying +`repo: stacklok/toolhive`. With vMCP, you pre-configure this default - engineers +never specify the repo parameter, and they can't accidentally query the wrong +repository. This eliminates hundreds of repetitive parameter entries per week. + +**Example scenario**: Configure staging database as the default (safe for +development), while production queries require an explicit approval gate. +Connection details are centralized in vMCP configuration instead of scattered +across individual tool configurations. + +### Authentication boundary separation + +Different authentication is needed for clients versus backend MCP servers, and +managing credentials across multiple systems is complex. vMCP implements a +two-boundary auth model that separates these concerns. + +**How it works**: Clients authenticate to vMCP using OAuth 2.1 authorization as +defined in the MCP specification. vMCP then handles authentication to each +backend MCP server independently. Revoking access is simple: disable the user in +your identity provider and all backend access is revoked instantly. + +This approach provides single sign-on for users, centralized access control, and +a complete audit trail. + +## When to use vMCP + +### Good fit + +- Teams managing 5+ MCP servers (local or remote) +- Tasks requiring coordination across multiple systems +- Centralized authentication and authorization requirements +- Workflows that should be reusable across the team +- Security policies that need centralized enforcement +- Aggregating external SaaS MCP servers with internal tools + +### Not needed + +- Single MCP server usage +- Simple, one-step operations +- No orchestration requirements + +## Summary + +vMCP transforms MCP from individual servers into a unified orchestration +platform. It aggregates both container-based MCPServer resources and remote +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. + +## 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) +- [Optimize tool discovery](../guides-vmcp/optimizer.mdx) +- [Proxy remote MCP servers](../guides-k8s/remote-mcp-proxy.mdx) diff --git a/versioned_docs/version-1.0/toolhive/contributing.mdx b/versioned_docs/version-1.0/toolhive/contributing.mdx new file mode 100644 index 00000000..1b061c71 --- /dev/null +++ b/versioned_docs/version-1.0/toolhive/contributing.mdx @@ -0,0 +1,194 @@ +--- +title: Contributing to ToolHive +sidebar_label: Contributing +description: Learn how to contribute to ToolHive and its ecosystem of projects. +--- + +Thank you for your interest in contributing to ToolHive! This page provides an +overview of the project's architecture and links to resources for contributing +to each component. + +## Project overview + +ToolHive is composed of several independently developed components, each with +its own codebase, contributing guide, and development workflow. The components +work together to provide a complete platform for running and managing Model +Context Protocol (MCP) servers. + +All ToolHive components are open source and licensed under the Apache 2.0 +license. + +## Project components + +### ToolHive CLI, API, and Kubernetes Operator + +The core ToolHive repository contains the command-line interface, API server, +and Kubernetes operator. These components share a common codebase and provide +the runtime environment for deploying and managing MCP servers. + +**Repository**: [stacklok/toolhive](https://github.com/stacklok/toolhive) + +**Key resources**: + +- [Contributing guide](https://github.com/stacklok/toolhive/blob/main/CONTRIBUTING.md) +- [Developer documentation](https://github.com/stacklok/toolhive/blob/main/docs/README.md) +- [Kubernetes Operator developer guide](https://github.com/stacklok/toolhive/blob/main/cmd/thv-operator/README.md) +- [Issue tracker](https://github.com/stacklok/toolhive/issues) + +### ToolHive desktop UI + +The ToolHive Desktop UI is a cross-platform application that provides a +graphical interface for discovering, installing, and managing MCP servers. It's +built with TypeScript and Electron, and runs on macOS, Windows, and Linux. + +**Repository**: +[stacklok/toolhive-studio](https://github.com/stacklok/toolhive-studio) + +**Key resources**: + +- [Contributing guide](https://github.com/stacklok/toolhive-studio/blob/main/CONTRIBUTING.md) +- [Developer documentation](https://github.com/stacklok/toolhive-studio/blob/main/docs/README.md) +- [Issue tracker](https://github.com/stacklok/toolhive-studio/issues) + +### ToolHive Cloud UI + +The ToolHive Cloud UI is a web application for visualizing MCP servers running +in user infrastructure with easy URL copying for integration with AI agents. +Built with Next.js and TypeScript, this is an experimental project that is +actively being developed and tested. + +**Repository**: +[stacklok/toolhive-cloud-ui](https://github.com/stacklok/toolhive-cloud-ui) + +**Key resources**: + +- [Contributing guide](https://github.com/stacklok/toolhive-cloud-ui/blob/main/CONTRIBUTING.md) +- [Issue tracker](https://github.com/stacklok/toolhive-cloud-ui/issues) + +### Registry server + +The Registry Server is an API server that implements the official MCP Registry +API. It provides standardized access to MCP servers from multiple backends, +including file-based and other API-compliant registries. + +**Repository**: +[stacklok/toolhive-registry-server](https://github.com/stacklok/toolhive-registry-server) + +**Key resources**: + +- [Contributing guide](https://github.com/stacklok/toolhive-registry-server/blob/main/CONTRIBUTING.md) +- [Issue tracker](https://github.com/stacklok/toolhive-registry-server/issues) + +### Built-in registry + +The built-in registry contains the curated list of MCP servers available in +ToolHive. If you want to add a new MCP server to the registry, this is the +repository to contribute to. + +**Repository**: +[stacklok/toolhive-catalog](https://github.com/stacklok/toolhive-catalog) + +**Key resources**: + +- [Contributing guide](https://github.com/stacklok/toolhive-catalog/blob/main/CONTRIBUTING.md) +- [Registry inclusion criteria](./concepts/registry-criteria.mdx) +- [Submit a new MCP server](https://github.com/stacklok/toolhive-catalog/issues/new?template=add-an-mcp-server.md) +- [Issue tracker](https://github.com/stacklok/toolhive-catalog/issues) + +### Dockyard + +Dockyard is a tool that packages MCP servers into containers. It handles the +containerization process, making it easy to run MCP servers in isolated +environments. + +**Repository**: [stacklok/dockyard](https://github.com/stacklok/dockyard) + +**Key resources**: + +- [Contributing guide](https://github.com/stacklok/dockyard/blob/main/CONTRIBUTING.md) +- [Issue tracker](https://github.com/stacklok/dockyard/issues) + +### MCP Optimizer + +The MCP Optimizer acts as an intelligent intermediary between AI clients and MCP +servers. It provides tool discovery, unified access to multiple MCP servers +through a single endpoint, and intelligent routing. The optimizer reduces token +usage by narrowing down the toolset to only relevant tools for each request. + +**Repository**: +[StacklokLabs/mcp-optimizer](https://github.com/StacklokLabs/mcp-optimizer) + +**Key resources**: + +- [Contributing guide](https://github.com/StacklokLabs/mcp-optimizer/blob/main/CONTRIBUTING.md) +- [Usage tutorial](./tutorials/mcp-optimizer.mdx) +- [Documentation](https://github.com/StacklokLabs/mcp-optimizer/tree/main/docs) +- [Issue tracker](https://github.com/StacklokLabs/mcp-optimizer/issues) + +### Documentation website + +The documentation website (this site) is built with Docusaurus and contains +guides, tutorials, and reference documentation for all ToolHive components. + +**Repository**: +[stacklok/docs-website](https://github.com/stacklok/docs-website) + +**Key resources**: + +- [Contributing guide](https://github.com/stacklok/docs-website/blob/main/CONTRIBUTING.md) +- [Writing style guide](https://github.com/stacklok/docs-website/blob/main/STYLE-GUIDE.md) +- [Issue tracker](https://github.com/stacklok/docs-website/issues) + +## Ways to contribute + +We welcome contributions of all kinds, and no contribution is too small. Whether +you're fixing a typo, improving documentation, or adding a major feature, your +help is appreciated. First-time contributors are especially welcome! + +Here are some ways you can contribute to ToolHive: + +- **Code**: Fix bugs, add features, or improve performance in any of the project + components. +- **Documentation**: Write guides, improve existing docs, add examples, or fix + typos. +- **Testing**: Test new features, report bugs, or contribute automated tests. +- **Bug triage**: Help review and reproduce issues reported by others. +- **Examples and tutorials**: Create sample projects or write tutorials showing + how to use ToolHive. +- **MCP servers**: Submit new MCP servers to the registry or improve existing + ones. +- **Community support**: Help answer questions in GitHub issues or on Discord. +- **Design and UX**: Contribute to the UI design or suggest improvements to the + user experience. + +## Getting started + +Ready to contribute? Here are some ways to get involved: + +1. **Explore the codebase**: Browse the repositories that interest you and read + through the contributing guides to understand the development workflow. + +2. **Find an issue**: Look for issues labeled `good first issue` or + `help wanted` in the issue trackers. These are great starting points for new + contributors. + +3. **Join the community**: Connect with other contributors in the + [Stacklok Discord](https://discord.gg/stacklok) community. The + `#toolhive-developers` channel is dedicated to technical discussions. + +4. **Report bugs**: If you find a bug, open an issue in the appropriate + repository with a clear description and steps to reproduce. + +5. **Suggest features**: Have an idea for a new feature? Open an issue to + discuss it with the maintainers before starting work. + +## Code of conduct + +All contributors are expected to follow the +[Stacklok Code of Conduct](https://github.com/stacklok/toolhive/blob/main/CODE_OF_CONDUCT.md). +We're committed to providing a welcoming and inclusive environment for everyone. + +## Additional resources + +- [Frequently asked questions](./faq.mdx) +- [Stacklok Discord community](https://discord.gg/stacklok) diff --git a/versioned_docs/version-1.0/toolhive/enterprise.mdx b/versioned_docs/version-1.0/toolhive/enterprise.mdx new file mode 100644 index 00000000..b949af93 --- /dev/null +++ b/versioned_docs/version-1.0/toolhive/enterprise.mdx @@ -0,0 +1,322 @@ +--- +title: Stacklok Enterprise +description: Stacklok Enterprise offerings for ToolHive +--- + +import HubSpotForm from '@site/src/components/HubSpotForm'; +import Heading from '@theme/Heading'; +import BrandedList from '@site/src/components/BrandedList'; + +
+ Running in production at major financial services, technology, and software
+ companies,
+ including Fortune 500 and Global 2000 enterprises
+
+
+
+How does Stacklok Enterprise relate to ToolHive Community?
+ +ToolHive Community is an open source distribution optimized for individual +developers and pre-production use, making it the right tool for evaluating MCP +and building a proof of concept. Stacklok Enterprise is a separate, hardened +distribution built for production: semantically versioned, with IdP integration, +centralized governance, and SLA-backed support. Moving from Community to +Enterprise is a supported migration where Stacklok provides the enterprise +binaries and dedicated engineering support to take you from proof of concept to +production. +[See the full comparison](#toolhive-community-vs-stacklok-enterprise) or +[learn about the proof of concept engagement](#validate-stacklok-enterprise-in-your-environment). + +
+
+
+What happens to my data if I end my Enterprise contract?
+ +Your data never leaves your environment. Stacklok Enterprise is fully +self-hosted: you retain complete control over your data and infrastructure, +regardless of contract status. If you end your subscription, you can downgrade +to the open-source version at any time. The only things you lose are access to +Enterprise features, forward-deployed engineers, backported security patches, +and dedicated support. There is zero vendor lock-in. +[Learn more about the product offerings](#product-offerings). + +
+
+
+How long does a typical deployment take?
+ +Most customers begin to see value in less than 2 weeks of contract signing. +Stacklok works directly with your platform team, and every Enterprise license +includes dedicated engineering support throughout the process. You will need an +existing Kubernetes environment to get started. Timelines are scoped to your +environment, so if your situation is more complex, Stacklok will work at your +pace. +[Learn about the proof of concept engagement](#validate-stacklok-enterprise-in-your-environment). + +
+
+
+Why should I use an MCP platform instead of running MCP servers directly?
+ +Running MCP servers directly gives you no isolation, no access controls, and no +visibility into what those servers are doing. Stacklok Enterprise addresses this +by running each server in its own container with least-privilege permissions, +encrypting credentials at rest, and tracing every tool call via OpenTelemetry. +Stacklok Enterprise adds centralized governance, IdP-backed authentication, and +audit logging for teams running MCP at scale across their organization. +[Explore the core concepts](./concepts/) to dig deeper into how ToolHive works. + +
+
+
+What AI clients work with Stacklok Enterprise?
+ +Stacklok Enterprise works with any AI coding assistant or agent that supports +MCP. This includes Claude Code, GitHub Copilot, Cursor, Windsurf, VS Code, Zed, +Cline, Continue, Roo Code, Goose, LM Studio, OpenAI Codex, and many more. Most +clients support automatic configuration so developers can connect without manual +setup. +[See the full client compatibility reference](./reference/client-compatibility.mdx) +for the complete list. + +
+
+
+---
+
+## Explore ToolHive Community
+
+:::tip[Not ready for Stacklok Enterprise yet?]
+
+ToolHive Community is free, open source, and the best way to evaluate MCP before
+moving to production.
+
+[Get started with ToolHive Community →](./index.mdx)
+
+:::
diff --git a/versioned_docs/version-1.0/toolhive/faq.mdx b/versioned_docs/version-1.0/toolhive/faq.mdx
new file mode 100644
index 00000000..5a4d1fc6
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/faq.mdx
@@ -0,0 +1,237 @@
+---
+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.
+
+### Can I use ToolHive UI and the CLI together?
+
+Yes, but ToolHive UI manages the CLI automatically. When you install ToolHive
+UI, it creates a symlink to its bundled CLI and configures your PATH. You can
+use the `thv` command from your terminal—it uses the UI-managed version.
+
+If you have a standalone CLI installed separately (via Homebrew, WinGet, or
+manually), it will conflict with the UI-managed version and show an error.
+Uninstall the standalone version to resolve this.
+
+For more information, see the [CLI access guide](./guides-ui/cli-access.mdx) and
+[CLI conflict resolution](./guides-cli/install.mdx#cli-conflict-resolution).
+
+## 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.mdx#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.
+
+:::
+
+## Privacy and data collection
+
+### Does ToolHive collect any data?
+
+ToolHive collects anonymous usage metrics to help improve the product. These
+metrics include only tool call counts and are completely anonymous. No personal
+information, user identifiers, or sensitive data is collected.
+
+The metrics collection:
+
+- Is enabled by default
+- Only tracks the number of tool calls
+- Uses a randomly generated instance ID (not tied to your identity)
+- Is automatically disabled in CI environments
+- Can be easily disabled
+
+### How do I disable usage metrics?
+
+You can opt out of usage metrics collection in two ways:
+
+**Option 1: Persistent configuration (recommended)**
+
+Use the ToolHive CLI to disable metrics permanently:
+
+```bash
+thv config usage-metrics disable
+```
+
+**Option 2: Environment variable**
+
+Set an environment variable to disable metrics for the current session:
+
+```bash
+export TOOLHIVE_USAGE_METRICS_ENABLED=false
+```
+
+Once you opt out, ToolHive stops collecting and sending usage metrics. You need
+to restart any running servers for the change to take effect.
+
+## 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.mdx), 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-catalog/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/versioned_docs/version-1.0/toolhive/guides-cli/advanced-cicd.mdx b/versioned_docs/version-1.0/toolhive/guides-cli/advanced-cicd.mdx
new file mode 100644
index 00000000..f803324f
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-cli/advanced-cicd.mdx
@@ -0,0 +1,318 @@
+---
+title: Advanced CI/CD patterns
+description:
+ Advanced CI/CD patterns for building and deploying MCP server containers with
+ ToolHive.
+---
+
+This guide covers advanced CI/CD patterns for building MCP server containers
+using ToolHive's [`thv build`](../reference/cli/thv_build.md) command. These
+patterns include multi-architecture builds, supply chain security, and efficient
+change detection.
+
+These patterns are intended for anyone building MCP server containers regularly,
+such as maintainers of MCP servers or organizations deploying custom servers or
+repackaging existing ones.
+
+## Prerequisites
+
+Before implementing these advanced patterns, ensure you have:
+
+- Basic understanding of [`thv build`](./build-containers.mdx) command
+- Experience with CI/CD pipelines (GitHub Actions, GitLab CI, etc.)
+- Container registry access for pushing images
+- Understanding of Docker Buildx for multi-architecture builds
+
+## Multi-architecture MCP server builds
+
+Build MCP server containers for multiple architectures (amd64, arm64) using
+Docker Buildx:
+
+```yaml
+name: Multi-arch Build
+on:
+ push:
+ tags: ['v*']
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up QEMU
+ uses: docker/setup-qemu-action@v3
+
+ - name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@v3
+
+ - name: Install ToolHive
+ uses: StacklokLabs/toolhive-actions/install@v0
+ with:
+ version: latest
+
+ - name: Generate Dockerfile
+ run: |
+ thv build --dry-run --output Dockerfile uvx://mcp-server-git
+
+ - name: Build multi-arch container
+ run: |
+ docker buildx build \
+ --platform linux/amd64,linux/arm64 \
+ --tag ghcr.io/myorg/mcp-server:${{ github.ref_name }} \
+ --push \
+ .
+```
+
+## Supply chain security
+
+Enhance security with SBOM generation, provenance attestation, and image
+signing:
+
+```yaml
+name: Secure Build
+on:
+ push:
+ tags: ['v*']
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ packages: write
+ id-token: write
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Install Cosign
+ uses: sigstore/cosign-installer@v3
+
+ - name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@v3
+
+ - name: Install ToolHive
+ uses: StacklokLabs/toolhive-actions/install@v0
+ with:
+ version: latest
+
+ - name: Generate Dockerfile
+ run: |
+ thv build --dry-run --output Dockerfile uvx://mcp-server-git
+
+ - name: Build with security features
+ uses: docker/build-push-action@v6
+ id: build
+ with:
+ context: .
+ platforms: linux/amd64,linux/arm64
+ push: true
+ tags: ghcr.io/myorg/mcp-server:${{ github.ref_name }}
+ sbom: true # Generate Software Bill of Materials
+ provenance: true # Generate build provenance
+ cache-from: type=gha
+ cache-to: type=gha,mode=max
+
+ - name: Sign container image
+ env:
+ DIGEST: ${{ steps.build.outputs.digest }}
+ run: |
+ cosign sign --yes ghcr.io/myorg/mcp-server@${DIGEST}
+```
+
+## Efficient change detection
+
+Build only when relevant files change to optimize CI/CD performance:
+
+```yaml
+name: Conditional Build
+on:
+ push:
+ branches: [main]
+ pull_request:
+ branches: [main]
+
+jobs:
+ detect-changes:
+ runs-on: ubuntu-latest
+ outputs:
+ build_needed: ${{ steps.changes.outputs.build_needed }}
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ fetch-depth: 2
+
+ - name: Detect changes
+ id: changes
+ run: |
+ # Check if MCP server configs or Dockerfiles changed
+ if git diff --name-only HEAD~1..HEAD | grep -E "(mcp-configs/|Dockerfile|\.thv)"; then
+ echo "build_needed=true" >> $GITHUB_OUTPUT
+ else
+ echo "build_needed=false" >> $GITHUB_OUTPUT
+ fi
+
+ build:
+ needs: detect-changes
+ if: needs.detect-changes.outputs.build_needed == 'true'
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Install ToolHive
+ uses: StacklokLabs/toolhive-actions/install@v0
+ with:
+ version: latest
+
+ - name: Build containers
+ run: |
+ thv build --tag ghcr.io/myorg/mcp-server:latest uvx://mcp-server-git
+```
+
+## Matrix builds for multiple servers
+
+Build multiple MCP servers in parallel using matrix strategies:
+
+```yaml
+name: Matrix Build
+on:
+ push:
+ tags: ['v*']
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ strategy:
+ matrix:
+ server:
+ - name: git-server
+ scheme: uvx://mcp-server-git
+ - name: filesystem-server
+ scheme: npx://@modelcontextprotocol/server-filesystem
+ - name: custom-server
+ scheme: go://github.com/myorg/custom-mcp-server@latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Install ToolHive
+ uses: StacklokLabs/toolhive-actions/install@v0
+ with:
+ version: latest
+
+ - name: Build ${{ matrix.server.name }}
+ run: |
+ thv build --tag ghcr.io/myorg/${{ matrix.server.name }}:${{ github.ref_name }} \
+ ${{ matrix.server.scheme }}
+
+ - name: Push ${{ matrix.server.name }}
+ run: |
+ docker push ghcr.io/myorg/${{ matrix.server.name }}:${{ github.ref_name }}
+```
+
+## Vulnerability scanning
+
+Integrate security scanning into your build pipeline:
+
+```yaml
+name: Secure Build with Scanning
+on:
+ push:
+ tags: ['v*']
+
+jobs:
+ build-and-scan:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Install ToolHive
+ uses: StacklokLabs/toolhive-actions/install@v0
+ with:
+ version: latest
+
+ - name: Build container
+ run: |
+ thv build --tag mcp-server:scan uvx://mcp-server-git
+
+ - name: Run Trivy vulnerability scanner
+ uses: aquasecurity/trivy-action@master
+ with:
+ image-ref: 'mcp-server:scan'
+ format: 'sarif'
+ output: 'trivy-results.sarif'
+
+ - name: Upload Trivy scan results
+ uses: github/codeql-action/upload-sarif@v3
+ if: always()
+ with:
+ sarif_file: 'trivy-results.sarif'
+
+ - name: Tag and push if scan passes
+ run: |
+ docker tag mcp-server:scan ghcr.io/myorg/mcp-server:${{ github.ref_name }}
+ docker push ghcr.io/myorg/mcp-server:${{ github.ref_name }}
+```
+
+## GitLab CI example
+
+For GitLab CI users, here's an equivalent pipeline:
+
+```yaml
+# .gitlab-ci.yml
+stages:
+ - build
+ - security
+ - deploy
+
+variables:
+ DOCKER_DRIVER: overlay2
+ DOCKER_TLS_CERTDIR: '/certs'
+
+build:
+ stage: build
+ image: docker:latest
+ services:
+ - docker:dind
+ before_script:
+ # Install ToolHive CLI using curl and jq to get the latest version
+ - |
+ VERSION=$(curl -s https://api.github.com/repos/stacklok/toolhive/releases/latest | jq -r .tag_name)
+ wget "https://github.com/stacklok/toolhive/releases/download/${VERSION}/toolhive_${VERSION#v}_linux_amd64.tar.gz"
+ tar -xzf "toolhive_${VERSION#v}_linux_amd64.tar.gz"
+ install -m 0755 thv /usr/local/bin/
+ - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
+ script:
+ - thv build --tag $CI_REGISTRY_IMAGE/mcp-server:$CI_COMMIT_TAG
+ uvx://mcp-server-git
+ - docker push $CI_REGISTRY_IMAGE/mcp-server:$CI_COMMIT_TAG
+ only:
+ - tags
+
+security_scan:
+ stage: security
+ image: aquasec/trivy:latest
+ script:
+ - trivy image --exit-code 1 --severity HIGH,CRITICAL
+ $CI_REGISTRY_IMAGE/mcp-server:$CI_COMMIT_TAG
+ only:
+ - tags
+```
+
+## Best practices
+
+When implementing advanced CI/CD patterns:
+
+1. **Use specific tags** instead of `latest` for production deployments
+2. **Implement proper caching** to speed up builds
+3. **Scan for vulnerabilities** before pushing to production registries
+4. **Sign images** for supply chain security
+5. **Use matrix builds** for multiple MCP servers
+6. **Implement change detection** to avoid unnecessary builds
+7. **Store sensitive data** in CI/CD secrets, not in code
+
+## 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/versioned_docs/version-1.0/toolhive/guides-cli/api-server.mdx b/versioned_docs/version-1.0/toolhive/guides-cli/api-server.mdx
new file mode 100644
index 00000000..ca8de827
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-cli/api-server.mdx
@@ -0,0 +1,89 @@
+---
+title: Run the API server
+description: How to run the local ToolHive API server.
+---
+
+ToolHive includes a built-in API server that provides a RESTful interface for
+interacting with MCP servers. The API server is useful for integrating ToolHive
+with other applications or automating tasks.
+
+:::note
+
+The API server isn't intended for production use. It's designed for local
+automation and UI development, and doesn't implement any authentication or
+authorization mechanisms.
+
+For production use cases, consider using the ToolHive Kubernetes operator, which
+provides a more robust and secure way to manage ToolHive instances in a
+multi-user environment.
+
+:::
+
+## Start the API server
+
+To start the API server, use the following command:
+
+```bash
+thv serve
+```
+
+This starts the API server on `localhost` (127.0.0.1) using the default port
+`8080`.
+
+Test the API server using `curl` or a web browser:
+
+```bash
+curl http://localhost:8080/api/v1beta/status
+```
+
+You should see a JSON response with the current ToolHive version.
+
+## Custom networking
+
+By default, the API server listens on `localhost` (127.0.0.1) port `8080`.
+
+You can specify a different port using the `--port` option:
+
+```bash
+thv serve --port Can I run custom MCP servers outside the Stacklok registry?
+ +Yes. Stacklok Enterprise starts with a base registry of vetted, hardened MCP +servers maintained by Stacklok. From there, you have full control to add your +own servers from public package managers, Docker images, remote URLs, or build a +private registry tailored to your organization. You are never limited to +Stacklok's catalog. +[See how to run MCP servers in Kubernetes](./guides-k8s/run-mcp-k8s.mdx) for the +full details. + +
+
+
+Build fails with network errors
+ +If builds fail with network connectivity issues: + +1. **Check internet connectivity** for downloading packages +2. **Configure CA certificates** for corporate environments: + + ```bash + thv config set-ca-cert /path/to/corporate-ca.crt + ``` + +3. **Use proxy settings** if required by your network +4. **Verify package names** and versions exist in the respective registries + +
+
+
+Invalid image tag format
+ +If you get image tag validation errors: + +1. **Use valid Docker image tag format**: `name:tag` or `registry/name:tag` +2. **Avoid special characters** except hyphens, underscores, and dots +3. **Use lowercase names** for compatibility +4. **Check tag length limits** (typically 128 characters) + +Example valid tags: + +```bash +thv build --tag my-server:latest uvx://package +thv build --tag ghcr.io/org/server:v1.0.0 npx://package +``` + +
+
+
+Package not found errors
+ +If the build fails because a package cannot be found: + +1. **Verify package exists** in the respective registry: + - Python: Check [PyPI](https://pypi.org/) + - Node.js: Check [npm](https://www.npmjs.com/) + - Go: Verify the module path and version + +2. **Check version specifiers**: + + ```bash + # Correct version formats + thv build uvx://package@1.0.0 + thv build npx://package@latest + thv build go://github.com/user/repo@v1.0.0 + ``` + +3. **For Go modules**, ensure the path includes the correct import path + +
+
diff --git a/versioned_docs/version-1.0/toolhive/guides-cli/client-configuration.mdx b/versioned_docs/version-1.0/toolhive/guides-cli/client-configuration.mdx
new file mode 100644
index 00000000..0bb06915
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-cli/client-configuration.mdx
@@ -0,0 +1,279 @@
+---
+title: Client configuration
+description: How to configure AI agent clients to work with ToolHive MCP servers.
+---
+
+import ClientIntro from '../_partials/_client-config-intro.mdx';
+
+Custom registry not being used
+ +If your custom package registry configuration isn't being applied: + +1. **Verify your build environment configuration**: + + ```bash + thv config get-build-env + ``` + +2. **Check the environment variable names** match what your package manager + expects (for example, `NPM_CONFIG_REGISTRY` for npm, `GOPROXY` for Go) + +3. **Use `--dry-run` to inspect the generated Dockerfile** and verify your + environment variables are being injected: + + ```bash + thv build --dry-run uvx://my-package + ``` + +4. **Ensure network connectivity** to your custom registry from inside the + container build environment + +
+
+ ```
+
+
+
+Client is not detected by `thv client setup`
+ +If ToolHive doesn't detect your client: + +1. Verify ToolHive supports your client in the + [Client compatibility reference](../reference/client-compatibility.mdx). + +2. Make sure you installed the client in its default location. ToolHive detects + clients based on their configuration files. If the client isn't in its + default location, ToolHive can't detect it. + +3. Try manually registering the client: + + ```bash + thv client register
+
+
+Client can't connect to MCP server
+ +If your client can't connect to the MCP server: + +1. Verify the MCP server is running: + + ```bash + thv list + ``` + + See [Test MCP servers](./test-mcp-servers.mdx) for help testing the MCP + server's availability. + +2. Check if the client is registered: + + ```bash + thv client status + ``` + +3. Restart your client application. + +
+
+ ```
+
+3. Make sure you properly configured the MCP server in your client.
+4. If the MCP server requires authentication or has authorization policies
+ applied, make sure the client has the necessary permissions to access the
+ tools.
+
+
+
+Client can connect but tools aren't available
+ +If your client connects to the MCP server but tools aren't available: + +1. Make sure the MCP server is running and accessible: + + ```bash + thv list + ``` + + See [Test MCP servers](./test-mcp-servers.mdx) for help testing the MCP + server's functionality. + +2. Check the MCP server logs: + + ```bash + thv logs
+
+
+Containerized client can't connect to MCP server
+ +When your MCP client runs in a container (like containerized LibreChat), it +can't reach the ToolHive proxy on your host machine using `localhost` due to +container network isolation. The ToolHive proxy runs as an OS process on the +host and provides access to containerized MCP servers. + +Configure your containerized client to use the appropriate host address for your +platform: + +- **Docker Desktop (macOS/Windows)**: `host.docker.internal` +- **Podman Desktop**: `host.containers.internal` +- **Docker Engine (Linux)**: `172.17.0.1` (or your custom bridge gateway IP) + +For example, change the MCP server URL from `http://localhost:8080/mcp` to +`http://host.docker.internal:8080/mcp` in your client configuration. + +
+
diff --git a/versioned_docs/version-1.0/toolhive/guides-cli/custom-permissions.mdx b/versioned_docs/version-1.0/toolhive/guides-cli/custom-permissions.mdx
new file mode 100644
index 00000000..2fa313fa
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-cli/custom-permissions.mdx
@@ -0,0 +1,237 @@
+---
+title: Custom permissions
+description:
+ How to create and apply file system permissions and network isolation for MCP
+ servers using permission profiles in ToolHive.
+---
+
+ToolHive includes a permission system that lets you control an MCP server's
+access to your host's file system and network resources. This helps you maintain
+security and ensures that MCP servers operate within defined boundaries.
+
+## Understanding permission profiles
+
+Permissions are defined using _permission profiles_—JSON files that specify both
+file system and network access rules for an MCP server. Each MCP server can use
+only one permission profile at a time, so you include all necessary permissions
+in a single profile.
+
+Permission profiles control two types of access:
+
+- **Host file system access** specifies paths on your host that are mounted into
+ the MCP server container — see [file system access](./filesystem-access.mdx)
+ for detailed examples
+- **Network access rules** let you restrict outbound HTTP(S) connectivity from
+ the MCP server — see [network isolation](./network-isolation.mdx) for
+ architecture details and examples
+
+### Profile structure
+
+Profiles are defined in JSON format and can include the following properties:
+
+- `read`: List of paths on your host file system that the MCP server can read
+- `write`: List of file system paths that the MCP server can write to (this also
+ implies read access)
+- `network`: Network access rules for inbound and outbound connections:
+ - `inbound`: Inbound network access rules, which include:
+ - `allow_host`: List of allowed hostnames that can send traffic to the MCP
+ server. If not specified, only the container's own hostname, `localhost`,
+ and `127.0.0.1` are allowed.
+ - `outbound`: Outbound network access rules, which include:
+ - `insecure_allow_all`: If set to `true`, allows unrestricted outbound
+ network access. This isn't recommended for production use.
+ - `allow_host`: List of allowed hostnames or IP addresses for outbound
+ connections. To allow all subdomains of a domain, prefix the domain with a
+ period (e.g., `.github.com` allows any subdomain of `github.com`).
+ Wildcards are not supported.
+ - `allow_port`: List of allowed ports for outbound connections
+
+## Default permissions in the ToolHive registry
+
+ToolHive includes default least-privilege permissions for MCP servers in the
+built-in registry. These defaults balance functionality and security, but you
+should review them to make sure they meet your specific requirements.
+
+View these permissions using the following command:
+
+```bash
+thv registry info VS Code can't connect to some streamable-http servers
+ +You might encounter errors with Visual Studio Code connecting to some +Python-based MCP servers using the Streamable HTTP transport protocol: + +```text +[info] Connection state: Error Error sending message to http://localhost:49574/mcp: TypeError: fetch failed +[error] Server exited before responding to `initialize` request. +``` + +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: + +1. Change the URL in your VS Code settings to add a trailing slash to the MCP + server URL. For example, change `http://localhost:49574/mcp` to + `http://localhost:49574/mcp/`. You'll need to re-apply this if you stop and + restart the MCP server. +2. If the MCP server supports SSE, switch to using the SSE transport instead of + Streamable HTTP. + +
+
+ ```
+
+ Look for the `Mounts` section to see how paths are mapped.
+
+5. Restart the server with the updated profile or corrected volume mount
+
+
diff --git a/versioned_docs/version-1.0/toolhive/guides-cli/group-management.mdx b/versioned_docs/version-1.0/toolhive/guides-cli/group-management.mdx
new file mode 100644
index 00000000..4370aae9
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-cli/group-management.mdx
@@ -0,0 +1,127 @@
+---
+title: Organize servers into groups
+description: How to organize MCP servers into logical groups and configure client access.
+---
+
+This guide explains how to organize your MCP servers into logical groups and
+configure which groups your MCP clients can access.
+
+:::tip[New to groups?]
+
+If you're not sure whether groups are right for your use case, see
+[Organizing MCP servers with groups](../concepts/groups.mdx) for an overview of
+when and why to use them.
+
+:::
+
+:::info[What's the default behavior?]
+
+All MCP servers are automatically assigned to the `default` group unless you
+specify otherwise. MCP clients configured without a specific group can access
+all servers in the `default` group.
+
+:::
+
+## Create and organize groups
+
+### Create a group
+
+```bash
+thv group create File system access issues
+ +If your MCP server can't access the file system as expected: + +1. Verify that the paths in your profile or volume flag are correct +2. Ensure the host paths exist and have the correct permissions + - The MCP server runs as a specific user inside the container, so the host + paths must be accessible to that user +3. Check that the permissions are set correctly (read/write) +4. Inspect the container's mounted paths to ensure they match your expectations: + + ```bash + docker inspect
+
+
+Permission denied errors
+ +If you see "permission denied" errors when running ToolHive: + +1. Make sure the binary is executable: + + ```bash + chmod +x /path/to/thv + ``` + +2. If using Docker on Linux, make sure your user has permission to access the + Docker socket: + + ```bash + sudo usermod -aG docker $USER + ``` + + (Log out and back in or run `newgrp docker` for this to take effect) + + See + [Docker documentation](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user) + for more details. + +
+
+ # repeat for each server
+ ```
+
+
+
+### Other issues
+
+For other installation issues, check the
+[GitHub issues page](https://github.com/stacklok/toolhive/issues) or join the
+[Discord community](https://discord.gg/stacklok).
diff --git a/versioned_docs/version-1.0/toolhive/guides-cli/manage-mcp-servers.mdx b/versioned_docs/version-1.0/toolhive/guides-cli/manage-mcp-servers.mdx
new file mode 100644
index 00000000..6b98a568
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-cli/manage-mcp-servers.mdx
@@ -0,0 +1,160 @@
+---
+title: Manage servers
+description: How to monitor and manage the lifecycle of MCP servers using ToolHive.
+---
+
+## Monitoring
+
+ToolHive provides visibility into the status of your MCP servers. You can check
+the status of running servers and view their logs using the ToolHive CLI.
+
+### List running servers
+
+To see all currently running MCP servers:
+
+```bash
+thv list
+```
+
+This shows details about each running server, including its name, package
+(container image), status, URL for connecting clients, group, and when it was
+created.
+
+To include stopped servers in the list:
+
+```bash
+thv list --all
+```
+
+### View server logs
+
+To view logs for an MCP server, use the
+[`thv logs`](../reference/cli/thv_logs.md) command. You can optionally follow
+the logs with the `--follow` option, which shows the most recent log entries and
+updates in real time.
+
+#### Container logs
+
+For local servers, view the container logs:
+
+```bash
+thv logs Upgrade error on Windows
+ +If you encounter an error when upgrading ToolHive on Windows, it may be due to +the ToolHive executable being locked by a running MCP server proxy. + +```text title="Error example" +An unexpected error occurred while executing the command: +remove: Access is denied.: "C:\Users\USERNAME\AppData\Local\Microsoft\WinGet\Packages\stacklok.thv_Microsoft.Winget.Source_8wekyb3d8bbwe\thv.exe" +Uninstall failed with exit code: 0x8a150003 : Executing command failed +``` + +To resolve this: + +1. Stop all running MCP servers: + + ```powershell + thv stop --all + ``` + +2. After stopping all servers, run the upgrade command again: + + ```powershell + winget upgrade stacklok.thv + ``` + +3. If you still encounter issues, check if any ToolHive processes are still + running in the background. You can use Task Manager to end any lingering + `thv.exe` processes. + +4. Restart your MCP servers: + + ```powershell + thv list --all + thv restart
+-egress
+ ```
+
+ Look for messages indicating denied connections.
+
+4. Try temporarily using the default `network` profile to confirm it's a
+ permissions issue:
+
+ ```bash
+ thv run --isolate-network --permission-profile network
+ ```
+
+5. If the default profile works, review the egress proxy logs to identify which
+ specific permissions are missing in your custom profile.
+
+
diff --git a/versioned_docs/version-1.0/toolhive/guides-cli/quickstart.mdx b/versioned_docs/version-1.0/toolhive/guides-cli/quickstart.mdx
new file mode 100644
index 00000000..35725d5e
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-cli/quickstart.mdx
@@ -0,0 +1,335 @@
+---
+title: 'Quickstart: ToolHive CLI'
+sidebar_label: Quickstart
+description:
+ A step-by-step guide to installing the ToolHive CLI and running your first MCP
+ server.
+---
+
+In this tutorial, you'll install the ToolHive command-line application and run
+your first MCP server. By the end, you'll have a working MCP server that can
+fetch content from websites and be used by AI applications like GitHub Copilot
+or Cursor.
+
+## What you'll learn
+
+- How to install ToolHive on your system
+- How to find available MCP servers
+- How to run an MCP server
+- How to verify the server is working
+- How to use the server with an AI client application
+
+## Prerequisites
+
+Before starting this tutorial, make sure you have:
+
+- [Docker](https://docs.docker.com/get-docker/) or
+ [Podman](https://podman-desktop.io/downloads) or
+ [Colima](https://github.com/abiosoft/colima) installed and running
+- A [supported MCP client](../reference/client-compatibility.mdx) like GitHub
+ Copilot in VS Code, Cursor, Claude Code, and more
+
+## Step 1: Install ToolHive
+
+First, install ToolHive on your system. ToolHive provides the `thv` command-line
+tool that manages MCP servers in secure containers.
+
+For detailed installation instructions, see the
+[installing ToolHive](../guides-cli/install.mdx) guide. Here's a quick summary:
+
+Network connectivity issues
+ +If your MCP server can't connect to external services: + +1. Verify that your profile allows the necessary hosts and ports +2. Check that the transport protocol (TCP/UDP) is allowed +3. Check the logs of the egress proxy container for blocked requests: + + ```bash + docker logs
+
+
+Server fails to start
+ +If the server fails to start, check: + +- Is Docker, Podman, or Colima running? +- Do you have internet access to pull the container image? +- Is the port already in use by another application? + +Try running with a specific port: + +```bash +thv run --proxy-port 8081 fetch +``` + +
+
+
+If you encounter any problems, please join our
+[Discord community](https://discord.gg/stacklok) for help.
diff --git a/versioned_docs/version-1.0/toolhive/guides-cli/registry.mdx b/versioned_docs/version-1.0/toolhive/guides-cli/registry.mdx
new file mode 100644
index 00000000..84a76aad
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-cli/registry.mdx
@@ -0,0 +1,397 @@
+---
+title: Explore the registry
+description: How to use the built-in registry to find MCP servers.
+---
+
+ToolHive includes a built-in registry of MCP servers with verified
+configurations that meet a
+[minimum quality standard](../concepts/registry-criteria.mdx), allowing you to
+discover and deploy high-quality tools effortlessly. Simply select one from the
+list and run it securely with a single command.
+
+## Find MCP servers
+
+To list all MCP servers in the ToolHive registry, run:
+
+```bash
+thv registry list
+```
+
+This command displays a list of servers with their name, description, tier
+(official or community), and the number of stars and downloads to help you
+identify the most popular and useful servers.
+
+Example output:
+
+```text
+NAME DESCRIPTION TIER STARS PULLS
+atlassian Model Context Protocol (MCP) server for Atlassian product... Community 2194 7789
+elasticsearch Connect to your Elasticsearch data directly from any MCP ... Official 305 5429
+everything This MCP server attempts to exercise all the features of ... Community 56714 10441
+fetch A Model Context Protocol server that provides web content... Community 56714 9078
+filesystem Node.js server implementing Model Context Protocol (MCP) ... Community 56714 14041
+firecrawl A powerful web scraping and content extraction MCP server... Official 3605 7630
+git A Model Context Protocol server for Git repository intera... Community 56714 7000
+github The GitHub MCP Server provides seamless integration with ... Official 16578 5000
+grafana A Model Context Protocol (MCP) server for Grafana that pr... Official 1014 4900
+k8s MKP is a Model Context Protocol (MCP) server for Kubernet... Community 32 8064
+
+<... trimmed for brevity ...>
+```
+
+You can also search by keyword to find servers related to a specific topic or
+capability:
+
+```bash
+thv search Client can't use the server
+ +If your AI client application can't use the server: + +- Make sure your client is registered with ToolHive (see Step 2) +- Check that your client is supported +- Restart your client to pick up the new configuration +- Verify the server is running with [`thv list`](../reference/cli/thv_list.md) + +proxy port: 5432| B[ToolHive proxy
process
Port: 5432] + B -->|Forwards to
host port: 9876| C[MCP container
Host: 9876 → Container: 7654
ENV: MCP_PORT=7654] + C -->|Response| B + B -->|Response| A +``` + +This is equivalent to running a Docker container with +`docker run -p
proxy port: 5432| B[ToolHive proxy
process
Port: 5432] + B -->|Forwards to
host port: 9876| C["MCP container
(--target-port 3000)
Host: 9876 → Container: 3000
ENV: MCP_PORT=3000"] + C -->|Response| B + B -->|Response| A +``` + +Some MCP servers use command-line arguments to specify their transport and port. +For example, if your server expects the transport type as a positional argument +and requires the `--port` flag, you can pass it like this: + +```bash +thv run --transport streamable-http --target-port
+
+
+Server fails to start
+ +If a server fails to start: + +1. Check if Docker, Podman, or Colima is running +2. Verify you have internet access to pull images +3. Check if the port is already in use +4. Look at the error message for specific issues + +
+
+ ```
+
+2. Verify the port isn't blocked by a firewall
+
+3. Make sure clients are properly configured (see
+ [Client configuration](./client-configuration.mdx))
+
+
+
+Server starts but isn't accessible
+ +If a server starts but isn't accessible: + +1. Check the server logs: + + ```bash + thv logs
+
+ ```
+
+3. Check if the server requires any secrets or environment variables
+
+4. Verify the server's configuration and arguments
+
+
+
+Server crashes or exits unexpectedly
+ +If a server crashes or exits unexpectedly: + +1. List all MCP servers including stopped ones: + + ```bash + thv list --all + ``` + +2. Check the logs for error messages: + + ```bash + thv logs
+
+ ```
+
+
+
+Remote server authentication fails
+ +If a remote MCP server authentication fails: + +1. Check the server logs for authentication errors (see + [View server logs](./manage-mcp-servers.mdx#view-server-logs) for the correct + log file path on your platform) + +2. Verify the issuer URL is correct and accessible + +3. Check if the OAuth client ID and secret are valid + +4. Ensure the remote server supports the OAuth flow you're using + +5. Try re-authenticating by restarting the server: + + ```bash + thv restart
+
+ ```
+
+5. Try running with debug mode for more detailed logs:
+
+ ```bash
+ thv run --debug https://api.example.com/mcp --name my-server
+ ```
+
+
+
+Remote server connection issues
+ +If you can't connect to a remote MCP server: + +1. Verify the remote server URL is correct and accessible + +2. Check your network connectivity: + + ```bash + curl -I https://api.example.com/mcp + ``` + +3. Check if the remote server requires specific headers or authentication + +4. Review the server logs for connection errors: + + ```bash + thv logs
+
diff --git a/versioned_docs/version-1.0/toolhive/guides-cli/secrets-management.mdx b/versioned_docs/version-1.0/toolhive/guides-cli/secrets-management.mdx
new file mode 100644
index 00000000..3bbbed6c
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-cli/secrets-management.mdx
@@ -0,0 +1,362 @@
+---
+title: Secrets management
+description: How to securely manage API tokens and other sensitive data in ToolHive.
+---
+
+MCP servers often need secrets like API tokens, connection strings, and other
+sensitive parameters. ToolHive provides built-in secrets management features,
+letting you manage these values securely without exposing them in plaintext
+configuration files.
+
+## Secrets providers
+
+ToolHive supports multiple secrets providers to fit different security and
+workflow requirements:
+
+- `encrypted` - ToolHive encrypts secrets using a password stored in your
+ operating system's keyring
+- `1password` - ToolHive retrieves secrets from a 1Password vault
+
+You can use only one provider at a time. To select your preferred provider, run:
+
+```bash
+thv secret setup
+```
+
+If you plan to use 1Password, first set up a 1Password service account and
+obtain an API token. See the 1Password tab below for details.
+
+MCP server can't connect to services on the same host
+ +When ToolHive runs MCP servers in containers, they can't reach services on your +host machine using `localhost` due to container network isolation. + +Replace `localhost` in your MCP server configuration with the appropriate host +address for your platform: + +- **Docker Desktop (macOS/Windows)**: `host.docker.internal` +- **Podman Desktop**: `host.containers.internal` +- **Docker Engine (Linux)**: `172.17.0.1` (or your custom bridge gateway IP) + +For example, change `http://localhost:3000` to +`http://host.docker.internal:3000`. + +
+
+
+Keyring access issues
+ +If you run into errors related to the system keyring: + +1. Make sure your system's keyring service is running +2. Check that you have the necessary permissions +3. On some Linux systems, you might need to install additional packages: + + ```bash + # For Debian/Ubuntu + sudo apt-get install gnome-keyring + + # For Fedora/RHEL + sudo dnf install gnome-keyring + ``` + +
+
+ ```
+
+3. Check that you're using the correct secret name and target environment
+ variable. Inspect the MCP server's expected environment variables in the
+ registry:
+
+ ```bash
+ thv registry info
+ ```
+
+4. Inspect the server logs for any errors:
+
+ ```bash
+ thv logs
+ ```
+
+
+
+Secret not available to MCP server
+ +If your MCP server can't access a secret: + +1. Verify the secret exists: + + ```bash + thv secret list + ``` + +2. Verify the secret value: + + ```bash + thv secret get
+
+
+Forgot encryption password
+ +If the keyring entry is lost or corrupted and you forget your encryption +password, you won't be able to access your secrets. In this case, delete the +[encrypted secrets file](#reset-your-secret-store) and recreate your secrets. + +
+//[section-name/]
+ ```
+
+
diff --git a/versioned_docs/version-1.0/toolhive/guides-cli/skills-management.mdx b/versioned_docs/version-1.0/toolhive/guides-cli/skills-management.mdx
new file mode 100644
index 00000000..1f107ac9
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-cli/skills-management.mdx
@@ -0,0 +1,434 @@
+---
+title: Manage agent skills
+sidebar_label: Agent skills
+description: How to install, distribute, and manage agent skills with the ToolHive CLI.
+---
+
+[Agent skills](https://agentskills.io/) are reusable bundles of instructions,
+scripts, and resources that teach AI agents how to perform specific tasks. While
+MCP servers provide **tools** (the raw capabilities an agent can call), skills
+provide the **knowledge** of when, why, and how to use those tools effectively.
+
+ToolHive lets you install skills from a
+[ToolHive Registry Server](../guides-registry/skills.mdx) (by name), OCI
+registries (by reference), or Git repositories (by URL), and manages their
+lifecycle across multiple AI clients.
+
+:::tip[New to skills?]
+
+If you're not sure what skills are or how they relate to MCP servers, see
+[Understanding skills](../concepts/skills.mdx) for a conceptual overview.
+
+:::
+
+## Prerequisites
+
+- The [ToolHive API server](./api-server.mdx) must be running. Start it in a
+ separate terminal window (the command blocks while running):
+
+ ```bash
+ thv serve
+ ```
+
+ The server must remain running while you use `thv skill` commands.
+
+ :::tip[Using the ToolHive desktop app?]
+
+ If the ToolHive desktop app is already running, the API server is available
+ automatically. You can skip the `thv serve` step and use `thv skill` commands
+ directly.
+
+ :::
+
+- A supported AI client installed. See the
+ [client compatibility reference](../reference/client-compatibility.mdx) for
+ which clients support skills.
+
+## Install a skill
+
+You can install skills from a ToolHive Registry Server (by name), an OCI
+registry (by reference), or a Git repository (by URL).
+
+### Install from the registry
+
+The simplest way to install a skill is by name. ToolHive looks up the skill in
+the configured Registry Server and installs it automatically:
+
+```bash
+thv skill install Issues accessing 1Password secrets
+ +If you can't access 1Password secrets: + +1. Verify the `OP_SERVICE_ACCOUNT_TOKEN` environment variable is set: + + ```bash + echo $OP_SERVICE_ACCOUNT_TOKEN + ``` + +2. Check that the token is valid and has the necessary permissions to access the + vault and item: + + ```bash + thv secret list + ``` + +3. Make sure the secret reference URI is correct and matches the vault, item, + and field names in 1Password: + + ```bash + thv secret get op://
+
+
+Skill command fails with a connection error
+ +All skill commands require the ToolHive API server to be running. Start it with: + +```bash +thv serve +``` + +Then retry your skill command. + +
+
+ ```
+
+3. Verify the skill files exist in the expected directory. For Claude Code,
+ user-scoped skills are at `~/.claude/skills//` and project-scoped
+ skills are at `/.claude/skills//`.
+
+4. Restart your AI client to trigger skill discovery.
+
+
+
+Skill not discovered by your AI client
+ +If your AI client doesn't see an installed skill: + +1. Verify the skill is installed: + + ```bash + thv skill list + ``` + +2. Check that the skill was installed for the correct client: + + ```bash + thv skill info
+
+
+Skill validation fails
+ +Run `thv skill validate` to see specific errors: + +```bash +thv skill validate ./my-skill +``` + +Common issues include: + +- Missing `SKILL.md` file in the directory +- Missing `name` or `description` in the frontmatter +- Skill `name` doesn't match the directory name +- Symlinks present in the skill directory (not allowed for security) + +
+
diff --git a/versioned_docs/version-1.0/toolhive/guides-cli/telemetry-and-metrics.mdx b/versioned_docs/version-1.0/toolhive/guides-cli/telemetry-and-metrics.mdx
new file mode 100644
index 00000000..16e6335a
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-cli/telemetry-and-metrics.mdx
@@ -0,0 +1,457 @@
+---
+title: Telemetry and metrics
+description:
+ How to enable OpenTelemetry and Prometheus instrumentation for ToolHive MCP
+ servers.
+---
+
+ToolHive includes built-in instrumentation using OpenTelemetry, which gives you
+comprehensive observability for your MCP server interactions. You can export
+traces and metrics to popular observability backends like Jaeger, Honeycomb,
+Datadog, and Grafana Cloud, or expose Prometheus metrics locally.
+
+## What you can monitor
+
+ToolHive's telemetry captures detailed information about MCP interactions
+including traces, metrics, and performance data. For a comprehensive overview of
+the telemetry architecture, metrics collection, and monitoring capabilities, see
+the [observability overview](../concepts/observability.mdx).
+
+## Enable telemetry
+
+You can enable telemetry when running an MCP server by using the OpenTelemetry
+flags with the [`thv run`](../reference/cli/thv_run.md) command or configure
+defaults for all MCP servers using the
+[`thv config otel`](../reference/cli/thv_config_otel.md) commands.
+
+### Export to an OTLP endpoint
+
+You can export traces and metrics to an OpenTelemetry Protocol (OTLP) compatible
+backend using the `--otel-endpoint` flag. You can also specify headers for
+authentication and configure sampling rates.
+
+This example runs the Fetch MCP server and exports traces to a local instance of
+the [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/):
+
+```bash
+thv run \
+ --otel-endpoint localhost:4318 \
+ --otel-service-name fetch-mcp \
+ --otel-insecure \
+ fetch
+```
+
+:::note
+
+The `--otel-endpoint` is provided as a hostname and optional port, without a
+scheme or path (e.g., use `api.honeycomb.io` or `api.honeycomb.io:443`, not
+`https://api.honeycomb.io`). ToolHive automatically uses HTTPS unless
+`--otel-insecure` is specified.
+
+:::
+
+By default, the service name is set to `thv-Push to registry fails with authentication error
+ +Make sure you're authenticated with your container registry: + +```bash +# For GitHub Container Registry +echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin + +# For Docker Hub +docker login +``` + +Then retry the push command. + +
+
+
+Traces not received by collector
+ +If traces aren't showing up in your backend: + +1. Verify the endpoint URL and authentication headers +2. Check network connectivity to the OTLP endpoint +3. Ensure sampling rate isn't too low (set to `1.0` temporarily for testing) +4. Check the ToolHive log file for errors related to telemetry (the log file + path is displayed when you start a server with `thv run`) +5. If your endpoint uses a self-signed certificate or a certificate from a + custom CA, use the `--thv-ca-bundle` flag to add your CA or self-signed + certificate. + +
+
+
+Prometheus metrics not available
+ +If the `/metrics` endpoint isn't accessible: + +1. Confirm `--otel-enable-prometheus-metrics-path` is set +2. Check that you're accessing the correct port +3. Verify no firewall is blocking the port + +
+
diff --git a/versioned_docs/version-1.0/toolhive/guides-cli/test-mcp-servers.mdx b/versioned_docs/version-1.0/toolhive/guides-cli/test-mcp-servers.mdx
new file mode 100644
index 00000000..37b70a69
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-cli/test-mcp-servers.mdx
@@ -0,0 +1,95 @@
+---
+title: Test MCP servers
+description: Learn how to test and validate MCP servers using the ToolHive CLI.
+---
+
+ToolHive includes several commands to help you test and validate MCP servers.
+These commands ensure that your servers are functioning correctly. This is
+useful for:
+
+- Validating new MCP server installations
+- Troubleshooting existing MCP servers
+- Testing custom MCP servers during development
+
+## MCP Inspector
+
+The [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) is an
+interactive tool for testing and debugging MCP servers.
+
+You can quickly launch the MCP Inspector and connect it to an MCP server running
+with ToolHive using the `thv inspector` command:
+
+```bash
+thv inspector High CPU or memory usage
+ +If telemetry is consuming too many resources on your system: + +1. Reduce the sampling rate with `--otel-sampling-rate` for specific servers or + globally with `thv config otel set-sampling-rate` +2. Only enable telemetry for servers you need to monitor +3. Monitor the resource usage of the OpenTelemetry Collector or other backend + services + +
+
+
+Overlays didn't apply
+ +- Ensure `.thvignore` exists in the mount source directory (not elsewhere) +- Confirm patterns match actual names relative to the mount source +- Run with `--print-resolved-overlays` and check the workload's log file path + displayed by `thv run` + +
+
+
+## Related information
+
+- [File system access](./filesystem-access.mdx)
+- [Run MCP servers](./run-mcp-servers.mdx)
+- [Network isolation](./network-isolation.mdx)
+- [`thv run` command reference](../reference/cli/thv_run.md)
diff --git a/versioned_docs/version-1.0/toolhive/guides-cli/token-exchange.mdx b/versioned_docs/version-1.0/toolhive/guides-cli/token-exchange.mdx
new file mode 100644
index 00000000..72a86409
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-cli/token-exchange.mdx
@@ -0,0 +1,210 @@
+---
+title: Configure token exchange for backend authentication
+description:
+ How to set up token exchange so MCP servers can authenticate to backend
+ services using ToolHive.
+---
+
+This guide shows you how to configure token exchange, which allows MCP servers
+to authenticate to backend APIs using short-lived, properly scoped tokens
+instead of embedded secrets.
+
+For conceptual background on how token exchange works and its security benefits,
+see [Backend authentication](../concepts/backend-auth.mdx), which includes a
+[sequence diagram](../concepts/backend-auth.mdx#same-idp-with-token-exchange)
+illustrating the complete flow.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- ToolHive installed and working
+- Basic familiarity with OAuth, OIDC, and JWT concepts
+- An identity provider that supports
+ [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693) token exchange (such
+ as Okta, Auth0, or Keycloak)
+- A backend service configured to accept tokens from your identity provider
+- Familiarity with [Authentication and authorization](./auth.mdx) setup in
+ ToolHive
+
+From your identity provider, you'll need:
+
+- Audience value for the MCP server
+- Issuer URL
+- JWKS URL (for key verification)
+- Token exchange endpoint URL
+- Client credentials for the token exchange client
+
+## Configure your identity provider
+
+Token exchange requires your identity provider to issue tokens for the backend
+service when presented with a valid MCP server token. The exact configuration
+steps vary by provider, but generally include:
+
+### Register a token exchange client
+
+Create an OAuth application in your identity provider for ToolHive to use when
+performing token exchange:
+
+- Note the client ID and client secret
+- Grant the application permission to use the
+ `urn:ietf:params:oauth:grant-type:token-exchange` grant type
+
+Token exchange is an authenticated flow—ToolHive uses these credentials to prove
+its identity when requesting exchanged tokens from the identity provider.
+
+:::tip[Okta]
+
+Create an API Services application for ToolHive and enable the token exchange
+grant type in the application settings.
+
+:::
+
+### Define audience and scopes for the backend service
+
+Configure your identity provider to recognize the backend service:
+
+- Define the audience value that identifies your backend service (for example,
+ `backend-api`)
+- Specify the scopes the backend service accepts (for example, `api:read`,
+ `api:write`)
+
+:::tip[Okta]
+
+Create a custom authorization server for the backend service and define the
+scopes under **Security > API > Authorization Servers**.
+
+:::
+
+### Create an access policy
+
+Set up a policy that permits token exchange and controls what scopes are
+included in exchanged tokens:
+
+- Enable the token exchange grant type for the ToolHive client
+- Define which users or groups can obtain tokens for the backend service
+- Specify the scopes included in exchanged tokens
+
+:::tip[Okta]
+
+Add a trust relationship from the MCP authorization server to the backend
+authorization server, then create access policies on the backend server to
+permit token exchange.
+
+Consult the
+[Okta token exchange documentation](https://developer.okta.com/docs/guides/set-up-token-exchange/main/)
+for detailed steps.
+
+:::
+
+## MCP server requirements
+
+The MCP server that ToolHive fronts must accept a per-request authentication
+token. Specifically, the server should:
+
+- Read the access token from the `Authorization: Bearer` header (or a custom
+ header if you configure `--token-exchange-header-name`)
+- Use this token to authenticate to the backend service
+- Not rely on hardcoded secrets or environment variables for backend
+ authentication
+
+ToolHive injects the exchanged token into each request, so the MCP server
+receives a fresh, properly scoped token for every call.
+
+:::tip[Example]
+
+The [Apollo MCP server](https://github.com/apollographql/apollo-mcp-server)
+supports token passthrough via its config
+(`disable_auth_token_passthrough: false`).
+
+:::
+
+## Run an MCP server with token exchange
+
+Once your identity provider is configured, start your MCP server with token
+exchange enabled:
+
+```bash
+thv run \
+ --oidc-audience Can't list a parent directory
+ +- On SELinux systems, listing a parent directory may fail even though specific + files are accessible. Probe individual paths instead (for example, `stat` or + `cat`). + +
+
+
+Kubernetes-specific issues
+ +**MCPServer resource issues:** + +- Check the MCPServer status: `kubectl get mcpserver -n toolhive-system` +- Describe the resource for details: + `kubectl describe mcpserver weather-server-k8s -n toolhive-system` + +**Service account issues:** + +- Verify the service account exists: `kubectl get sa -n client-apps mcp-client` +- Check RBAC permissions if needed + +**ConfigMap mounting issues:** + +- Verify the ConfigMap exists: + `kubectl get configmap -n toolhive-system authz-config` +- Check the ConfigMap content: + `kubectl get configmap authz-config -n toolhive-system -o yaml` + +**OIDC configuration issues:** + +- For external IdP: Ensure the issuer URL is accessible from within the cluster +- For Kubernetes auth: Ensure the Kubernetes API server has OIDC enabled +- Check that the JWKS URL returns valid keys + +**Network connectivity:** + +- Verify pods can reach the Kubernetes API server +- Check cluster DNS resolution +- Test service-to-service connectivity: + `kubectl exec -n client-apps deployment/mcp-client-app -- curl http://weather-server-k8s.toolhive-system.svc.cluster.local:8080` + +**ToolHive Operator issues:** + +- Check operator logs: + `kubectl logs -n toolhive-system -l app.kubernetes.io/name=toolhive-operator` +- Verify the operator is running: `kubectl get pods -n toolhive-system` + +
+/oauth/callback`)
+- Check that the upstream provider's issuer URL is accessible from within the
+ cluster
+- For OIDC providers, ensure the `/.well-known/openid-configuration` endpoint is
+ reachable from the proxy pod
+
+**JWT signing key issues:**
+
+- Verify signing key Secrets exist:
+ `kubectl get secret -n toolhive-system auth-server-signing-key`
+- Ensure the key format is correct (PEM-encoded RSA or EC private key)
+- Check proxy logs for key loading errors:
+ `kubectl logs -n toolhive-system -l app.kubernetes.io/name=weather-server-embedded`
+
+**OIDC configuration mismatch:**
+
+- Ensure the `oidcConfig.inline.issuer` on your `MCPServer` matches the `issuer`
+ in your `MCPExternalAuthConfig`
+- Verify the `resourceUrl` in `oidcConfig` matches the external URL of the MCP
+ server
+
+
diff --git a/versioned_docs/version-1.0/toolhive/guides-k8s/connect-clients.mdx b/versioned_docs/version-1.0/toolhive/guides-k8s/connect-clients.mdx
new file mode 100644
index 00000000..9ba6ed51
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-k8s/connect-clients.mdx
@@ -0,0 +1,1102 @@
+---
+title: Connect clients to MCP servers
+description:
+ Learn how to connect clients to your Kubernetes-hosted MCP servers in
+ ToolHive.
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Overview
+
+After deploying MCP servers in your Kubernetes cluster, you need to connect
+clients to use them. This guide covers two main connection scenarios:
+
+1. **External clients** - Connecting from outside the cluster using Ingress or
+ Gateway API to expose MCP servers
+2. **Internal clients** - Connecting from applications running within the same
+ Kubernetes cluster
+
+```mermaid
+flowchart TB
+ subgraph External["External clients"]
+ UI["ToolHive UI"]
+ CLI["ToolHive CLI"]
+ Other["Other MCP clients"]
+ end
+
+ subgraph K8s["Kubernetes cluster"]
+ Ingress["Ingress/Gateway"]
+
+ subgraph NS["MCP Namespace"]
+ ProxyService["Service: MCP proxy"]
+ ProxyPod["Pod: ToolHive proxy"]
+ MCPPod["Pod: MCP server"]
+ end
+
+ subgraph AppNS["App namespace"]
+ App["Your application"]
+ end
+ end
+
+ UI -->|HTTPS| Ingress
+ CLI -->|HTTPS| Ingress
+ Other -->|HTTPS| Ingress
+ Ingress --> ProxyService
+ ProxyService --> ProxyPod
+ ProxyPod --> MCPPod
+
+ App -->|HTTP| ProxyService
+```
+
+## Prerequisites
+
+- A Kubernetes cluster with MCP servers deployed (see
+ [Run MCP servers in Kubernetes](./run-mcp-k8s.mdx))
+- An Ingress controller or Gateway API implementation installed in your cluster
+ (for external access)
+- [`kubectl`](https://kubernetes.io/docs/tasks/tools/) configured to communicate
+ with your cluster
+
+## Connect from outside the cluster
+
+To make your MCP servers accessible to external clients like the ToolHive UI,
+ToolHive CLI, or other MCP clients, you need to expose the proxy service using
+an Ingress resource or Gateway API.
+
+:::info[Service naming convention]
+
+The ToolHive operator automatically creates a Kubernetes Service for each
+MCPServer, MCPRemoteProxy, and VirtualMCPServer resource using the following
+naming patterns using the resource name:
+
+- MCPServer: `mcp-Embedded authorization server issues
+ +**OAuth flow not initiating:** + +- Verify the `MCPExternalAuthConfig` resource exists in the same namespace: + `kubectl get mcpexternalauthconfig -n toolhive-system` +- Check that the `externalAuthConfigRef.name` in your `MCPServer` matches the + `MCPExternalAuthConfig` resource name +- Verify the upstream provider's client ID and redirect URI are correctly + configured in the `MCPExternalAuthConfig` + +**Token validation failures after restart:** + +- Ensure you have configured `signingKeySecretRefs` and `hmacSecretRefs` with + persistent keys +- Without these, ephemeral keys are generated on startup, invalidating all + previously issued tokens + +**Upstream IdP redirect errors:** + +- Verify the redirect URI configured in your upstream provider matches the + ToolHive proxy's callback URL (typically + `https://
+
+
+Ingress returns 503 Service Unavailable
+ +If your Ingress returns a 503 error: + +```bash +# Check if the service exists +kubectl get service -n toolhive-system mcp-fetch-proxy + +# Check the proxy pod is running +kubectl get pods -n toolhive-system -l app.kubernetes.io/instance=fetch + +# Check pod logs for errors +kubectl logs -n toolhive-system -l app.kubernetes.io/instance=fetch +``` + +Common causes: + +- **Proxy pod not running**: Ensure the MCPServer resource was created + successfully +- **Wrong service name**: The Ingress backend service name must follow the + naming conventions defined above +- **Wrong port**: The Ingress backend port must match the `proxyPort` in the + MCPServer spec +- **Pod health check failing**: Check the proxy pod logs for errors + +
+
+
+TLS certificate issues
+ +If you see certificate errors when connecting: + +```bash +# Check the certificate secret exists +kubectl get secret -n toolhive-system fetch-mcp-tls + +# Describe the secret to verify it contains tls.crt and tls.key +kubectl describe secret -n toolhive-system fetch-mcp-tls + +# If using cert-manager, check certificate status +kubectl get certificate -n toolhive-system + +# Check cert-manager logs +kubectl logs -n cert-manager -l app=cert-manager +``` + +Common causes: + +- **Certificate not ready**: Wait for cert-manager to provision the certificate + (can take a few minutes) +- **DNS not configured**: Ensure your domain points to the Ingress load balancer +- **Challenge validation failing**: Check cert-manager logs for ACME challenge + errors +- **Wrong ClusterIssuer**: Verify the cert-manager annotation references an + existing ClusterIssuer + +
+
+
+Authentication failures
+ +If OAuth authentication is failing when connecting to your MCP server: + +```bash +# Test if the OAuth metadata endpoint is accessible +# For host-based routing +curl https://fetch-mcp.example.com/.well-known/oauth-protected-resource + +# For path-based routing +curl https://mcp.example.com/.well-known/oauth-protected-resource/fetch/mcp + +# Check proxy logs for authentication errors +kubectl logs -n toolhive-system -l app.kubernetes.io/instance=fetch + +# Verify the MCPServer OIDC configuration +kubectl get mcpserver -n toolhive-system fetch -o yaml | grep -A15 oidcConfig +``` + +Common causes: + +- **`.well-known` endpoint not accessible**: When using path-based routing with + OAuth, you must configure your Ingress or HTTPRoute to forward the + `.well-known` path to the backend. See the "Path-based routing with OAuth" tab + in the Ingress or Gateway API sections above for configuration examples. +- **Missing or incorrect `resourceUrl`**: Ensure the `resourceUrl` in your + MCPServer's `oidcConfig` matches the client-facing URL (e.g., + `https://mcp.example.com/fetch/mcp` for path-based routing). +- **Token validation failure**: The token's `aud` claim must match the + configured audience in your MCPServer's OIDC configuration. +- **Issuer mismatch**: The token's `iss` claim must match the configured issuer. +- **JWKS endpoint unreachable**: Check that the proxy can reach your identity + provider's JWKS endpoint to validate tokens. + +For detailed OAuth setup and troubleshooting, see the +[Authentication and authorization](./auth-k8s.mdx) guide. + +
+
+
+Cannot connect from within cluster
+ +If pods cannot connect to the MCP server service: + +```bash +# Verify service exists +kubectl get service -n toolhive-system mcp-fetch-proxy + +# Check that pods are running +kubectl get pods -n toolhive-system -l app.kubernetes.io/instance=fetch + +# Test DNS resolution from a pod +kubectl run test-dns -n toolhive-system --image=busybox --restart=Never -- \ + nslookup mcp-fetch-proxy.toolhive-system.svc.cluster.local + +# Check the DNS test results +kubectl logs -n toolhive-system test-dns + +# Clean up the test pod +kubectl delete pod -n toolhive-system test-dns + +# Test connectivity from a pod +kubectl run test-curl -n toolhive-system --image=curlimages/curl --restart=Never -- \ + curl -X POST http://mcp-fetch-proxy:8080/mcp \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' + +# Check the connectivity test results +kubectl logs -n toolhive-system test-curl + +# Clean up the test pod +kubectl delete pod -n toolhive-system test-curl +``` + +Common causes: + +- **Network policies blocking traffic**: Check for network policies that might + prevent pod-to-pod communication +- **Wrong namespace**: Ensure you're using the correct service DNS name for + cross-namespace access +- **Service not created**: The operator automatically creates services, but + verify it exists +- **Wrong port**: Ensure you're using the `proxyPort` value from the MCPServer + spec +- **Wrong service name**: Remember the service name follows the naming + conventions defined above + +
+
+
+Gateway API not working
+ +If using Gateway API and connections fail: + +```bash +# Check Gateway status +kubectl get gateway -n toolhive-system mcp-gateway + +# Check HTTPRoute status +kubectl get httproute -n toolhive-system fetch-mcp-route + +# Describe the HTTPRoute for detailed status +kubectl describe httproute -n toolhive-system fetch-mcp-route + +# Check Gateway implementation logs (example for Istio) +kubectl logs -n istio-system -l app=istio-ingressgateway +``` + +Common causes: + +- **Gateway not ready**: Wait for the Gateway to be accepted and programmed by + the controller +- **Wrong gateway class**: Ensure `gatewayClassName` matches your installed + Gateway API implementation +- **Listener configuration issues**: Verify the Gateway listener configuration + matches the HTTPRoute requirements +- **Certificate issues**: For HTTPS, ensure the certificate reference exists and + is valid + +
+
diff --git a/versioned_docs/version-1.0/toolhive/guides-k8s/customize-tools.mdx b/versioned_docs/version-1.0/toolhive/guides-k8s/customize-tools.mdx
new file mode 100644
index 00000000..3d2453a4
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-k8s/customize-tools.mdx
@@ -0,0 +1,241 @@
+---
+title: Customize tools
+description: Filter and rename MCP server tools using the MCPToolConfig CRD and
+ toolConfigRef.
+---
+
+## Overview
+
+Use the MCPToolConfig Custom Resource Definition (CRD) to centrally manage which
+tools an MCP server exposes, and optionally rename tools or override their
+descriptions. You reference the configuration from an MCPServer using the
+`toolConfigRef` field.
+
+- toolsFilter: allow-list the tools to expose.
+- toolsOverride: rename tools and/or change their descriptions.
+- Same-namespace only: an MCPServer can reference only MCPToolConfig objects in
+ the same namespace.
+- Precedence: toolConfigRef takes precedence over the deprecated spec.tools
+ field on MCPServer.
+
+## Define a basic tool filter
+
+This example exposes only three tools on a server:
+
+```yaml title="toolconfig-basic.yaml"
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPToolConfig
+metadata:
+ name: basic-tool-filter
+ namespace: toolhive-system
+spec:
+ toolsFilter:
+ - read_file
+ - write_file
+ - list_directory
+```
+
+:::note[Empty filter]
+
+If `toolsFilter` is omitted or empty, all tools are allowed.
+
+:::
+
+## Rename tools and override descriptions
+
+You can rename tools to clearly distinguish different deployments or scopes, and
+refine their descriptions to add usage guidance.
+
+A common pattern is running the same MCP server multiple times for different
+scopes (for example, separate GitHub orgs, repos, or environments). Renaming
+tools makes intent obvious and helps prevent mistakes.
+
+```yaml title="toolconfig-with-overrides.yaml"
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPToolConfig
+metadata:
+ name: github-tools-config
+ namespace: toolhive-system
+spec:
+ # Only expose GitHub PR-related tools
+ toolsFilter:
+ - create_pull_request
+ - get_pull_request
+ - list_pull_requests
+ - merge_pull_request
+
+ # You can override name, description, or both (they are independent)
+ toolsOverride:
+ # Override only the name
+ create_pull_request:
+ name: github_create_pr
+
+ # Override only the description (keep the original name)
+ get_pull_request:
+ description: Retrieve details of a specific GitHub pull request
+
+ # Override both name and description
+ list_pull_requests:
+ name: github_list_prs
+ description: List pull requests in a repository
+
+ merge_pull_request:
+ name: github_merge_pr
+ description: Merge a GitHub pull request
+```
+
+The key in the `toolsOverride` map is the original tool name; the `name` field
+is the user-visible (overridden) name.
+
+:::info[Override fields]
+
+You can override name or description independently. Leave one unset to keep the
+original value from the MCP server. Both fields cannot be empty at the same
+time.
+
+:::
+
+:::tip[When to rename?]
+
+If you run the same server for different scopes (for example, prod vs. sandbox),
+use distinct tool names like `github_prod_create_pr` and
+`github_sandbox_create_pr` to make intent clear to clients.
+
+:::
+
+## Reference the configuration from an MCP server
+
+Add `toolConfigRef` to the `spec` section of your MCPServer or MCPRemoteProxy
+resource.
+
+Cross-namespace access denied
+ +If cross-namespace connections fail: + +```bash +# Check network policies in the MCP server namespace +kubectl get networkpolicy -n toolhive-system + +# Describe network policies to see rules +kubectl describe networkpolicy -n toolhive-system + +# Check if the app namespace has the required labels +kubectl get namespace my-app --show-labels +``` + +Solutions: + +- Create or update network policies to allow traffic from your app namespace +- Add required labels to your application namespace +- Test connectivity using a debug pod in the app namespace + +
+
+
+Authentication error with ghcr.io
+ +If you encounter an authentication error when pulling the Helm chart, it might +indicate a problem with your access to the GitHub Container Registry +(`ghcr.io`). + +ToolHive's charts and images are public, but if you've previously logged into +`ghcr.io` using a personal access token, you might need to re-authenticate if +your token has expired or been revoked. + +See the GitHub documentation to +[re-authenticate to the registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic). + +
+
+kubectl logs -n toolhive-system
+```
+
+Common causes include:
+
+- **Missing CRDs**: Ensure the CRDs were installed successfully before
+ installing the operator. The operator requires the CRDs to function properly.
+- **Configuration errors**: Check your `values.yaml` file for any
+ misconfigurations
+- **Insufficient permissions**: Ensure your cluster has the necessary RBAC
+ permissions for the operator to function
+- **Resource constraints**: Check if the cluster has sufficient CPU and memory
+ resources available
+- **Image pull issues**: Verify that the cluster can pull images from `ghcr.io`
+
+
+
+Operator pod fails to start
+ +If the operator pod is not starting or is in a `CrashLoopBackOff` state, check +the pod logs for error messages: + +```bash +kubectl get pods -n toolhive-system +# Note the name of the toolhive-operator pod + +kubectl describe pod -n toolhive-system
+ --overwrite
+done
+```
+
+Replace `` with the namespace you want to use going forward
+(for example, `toolhive-system`). This is a one-time operation. After patching,
+future upgrades work as long as you use the same namespace consistently.
+
+
+
+CRD upgrade fails with namespace mismatch
+ +If you see an error like the following when upgrading the CRD chart: + +```text +Error: invalid ownership metadata; annotation validation error: +key "meta.helm.sh/release-namespace" must equal "toolhive-system": +current value is "default" +``` + +This means the CRD chart was originally installed in a different namespace than +the one you're now targeting. To fix this, patch the +`meta.helm.sh/release-namespace` annotation on all CRDs to match your desired +namespace: + +```bash +for crd in $(kubectl get crd -o name | grep toolhive.stacklok.dev); do + kubectl annotate "$crd" \ + meta.helm.sh/release-namespace=
+
+```
+
+To reinstall the CRDs:
+
+```bash
+helm uninstall toolhive-operator-crds
+helm upgrade -i toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds
+```
+
+
+
+CRDs installation fails
+ +If the CRDs installation fails, you might see errors about existing resources or +permission issues: + +```bash +# Check if CRDs already exist +kubectl get crd | grep toolhive + +# Remove existing CRDs if needed (this will delete all related resources) +kubectl delete crd
+
+
+Namespace creation issues
+ +If you encounter permission errors when creating the `toolhive-system` +namespace, create it manually first: + +```bash +kubectl create namespace toolhive-system +``` + +Then install the operator without the `--create-namespace` flag: + +```bash +helm upgrade -i toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system +``` + +
+
+
+Helm chart not found
+ +If Helm cannot find the chart, ensure you're using the correct OCI registry URL +and that your Helm version supports OCI registries (v3.8.0+): + +```bash +# Check Helm version +helm version + +# Try pulling the chart explicitly +helm pull oci://ghcr.io/stacklok/toolhive/toolhive-operator +``` + +
+
diff --git a/versioned_docs/version-1.0/toolhive/guides-k8s/index.mdx b/versioned_docs/version-1.0/toolhive/guides-k8s/index.mdx
new file mode 100644
index 00000000..1e16a229
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-k8s/index.mdx
@@ -0,0 +1,20 @@
+---
+title: Using the ToolHive Kubernetes Operator
+description:
+ How-to guides for using the ToolHive Kubernetes operator to run and manage MCP
+ servers.
+---
+
+import DocCardList from '@theme/DocCardList';
+
+## Introduction
+
+The ToolHive Kubernetes operator manages MCP servers in Kubernetes clusters. It
+provides a way to deploy, manage, and scale MCP servers in multi-user
+environments. By defining MCP servers as Kubernetes resources, the operator
+automates their deployment and management, making it easier to run MCP servers
+in multi-user environments.
+
+## Contents
+
+Network connectivity issues
+ +If you're experiencing network timeouts or connection issues: + +- Verify your cluster has internet access to reach `ghcr.io` +- Check if your organization uses a proxy or firewall that might block access +- Consider using a private registry mirror if direct access is restricted + +Kubernetes cluster
"] + subgraph K8s1["**Deployment**"] + Svc1["HTTP ProxyService"] -- http --> Proxy1["HTTP Proxy
Pod"] -- stdio or http --> MCP1["MCP Server
Pod"] + Proxy1 -.->|creates| MCP1 + end + subgraph K8s2["**Deployment**"] + Svc2["HTTP Proxy
Service"] -- http --> Proxy2["HTTP Proxy
Pod"] -- stdio or http --> MCP2["MCP Server
Pod"] + Proxy2 -.->|creates| MCP2 + end + Ingress["Ingress"] -- http --> Svc1 & Svc2 + Operator["ToolHive
Operator"] -.->|creates| K8s1 & K8s2 + end + + Client["MCP Client
[ex: Copilot]"] -- http --> Ingress +``` + +`MCPRemoteProxy` and `VirtualMCPServer` resources work similarly, with the +operator managing a proxy pod that connects to remote MCP servers or aggregates +multiple backends, respectively. + +The diagram shows how clients connect to MCP servers through a standard Ingress +or Gateway. To learn how to expose your MCP servers and connect clients, see +[Connect clients to MCP servers](./connect-clients.mdx). + +## Installation + +[Deploy the ToolHive operator](./deploy-operator.mdx) in your Kubernetes +cluster. + +Once the operator is installed, you can create and manage MCP servers: + +- [Run MCP servers in Kubernetes](./run-mcp-k8s.mdx) +- [Proxy remote MCP servers](./remote-mcp-proxy.mdx) +- [Virtual MCP Server (vMCP)](../guides-vmcp/index.mdx) diff --git a/versioned_docs/version-1.0/toolhive/guides-k8s/logging.mdx b/versioned_docs/version-1.0/toolhive/guides-k8s/logging.mdx new file mode 100644 index 00000000..7a7bbb07 --- /dev/null +++ b/versioned_docs/version-1.0/toolhive/guides-k8s/logging.mdx @@ -0,0 +1,411 @@ +--- +title: Audit logging +description: Configure and manage logging for ToolHive in Kubernetes environments +--- + +ToolHive provides structured JSON logging for MCP servers in Kubernetes, giving +you detailed operational insights and compliance audit trails. You can configure +log levels, enable audit logging for tracking MCP operations, and integrate with +common log collection systems like Fluentd, Filebeat, and Splunk. + +## Overview + +The ToolHive operator provides two types of logs: + +1. **Standard application logs** - Structured operational logs from the ToolHive + operator and proxy components +2. **Audit logs** - Security and compliance logs tracking all MCP operations + +```mermaid +flowchart TB + subgraph Sources["Log sources"] + Op["ToolHive operator"] + Proxy["HTTP proxy pods"] + MCP["MCP server pods"] + end + + subgraph Processing["Log processing"] + Stdout["Standard output
(structured JSON)"] + Audit["Audit logger
(structured JSON)"] + end + + subgraph Destinations["Log destinations"] + K8s["Kubernetes logs"] + ELK["ELK stack"] + Splunk["Splunk"] + Datadog["Datadog"] + Etc["...other collectors"] + end + + Op --> Stdout + Proxy --> Stdout & Audit + MCP --> Stdout + + Stdout --> K8s + Audit --> K8s + + K8s --> ELK & Splunk & Datadog & Etc +``` + +## Structured application logs + +ToolHive automatically outputs structured JSON logs to the standard output +(stdout) of the operator and HTTP proxy (`proxyrunner`) pods. + +All logs use a consistent format for easy parsing by log collectors: + +```json +{ + "level": "info", + "ts": 1761934317.963125, + "caller": "logger/logger.go:39", + "msg": "MCP server github started successfully" +} +``` + +### Key fields in application logs + +| Field | Type | Description | +| -------- | ------ | ------------------------------------------------ | +| `level` | string | Log level: `debug`, `info`, `warn`, `error` | +| `ts` | float | Unix timestamp with microseconds | +| `caller` | string | Source file and line number of the log statement | +| `msg` | string | Log message (exact content varies by event) | + +## Enable audit logging + +Audit logs provide detailed records of all MCP operations for security and +compliance. To enable audit logging, set the `audit.enabled` field to `true` in +your MCP server manifest: + +
+
+
+## Set up log collection
+
+ToolHive outputs structured JSON logs that work with your existing log
+collection infrastructure. The examples below show basic host-based
+configurations for common log collectors. Adapt these patterns to match your
+organization's logging setup.
+
+:::note[Prerequisites]
+
+These examples assume:
+
+- Container logs are available at `/var/log/pods/`
+- You have a standard Kubernetes logging setup
+- Deployment manifests are handled separately
+- You're using host-based log collection
+
+:::
+
+:::tip[Use your existing collection methods]
+
+If your organization uses sidecar-based or operator-based log collection (such
+as Fluent Bit sidecars or the Fluentd Operator), adapt these configuration
+patterns to work with your existing infrastructure.
+
+:::
+
+### Configure Fluentd
+
+```text
+# fluentd.conf
+Complete audit field reference
+ +#### Audit log fields + +| Field | Type | Description | +| ---------------------------- | ------ | ----------------------------------------------------------------------- | +| `time` | string | Timestamp when the log was generated | +| `level` | string | Log level (INFO+2 for audit events) | +| `msg` | string | Always "audit_event" for audit logs | +| `audit_id` | string | Unique identifier for the audit event | +| `type` | string | Type of MCP operation (see event types below) | +| `logged_at` | string | UTC timestamp of the event | +| `outcome` | string | Result of the operation: `success` or `failure` | +| `component` | string | Name of the MCP server | +| `source` | object | Request source information | +| `source.type` | string | Source type (e.g., "network") | +| `source.value` | string | Source identifier (e.g., IP address) | +| `source.extra` | object | Additional source metadata | +| `subjects` | object | User and identity information | +| `subjects.user` | string | User display name (from JWT claims: name, preferred_username, or email) | +| `subjects.user_id` | string | User identifier (from JWT sub claim) | +| `subjects.client_name` | string | Client application name (optional, from JWT claims) | +| `subjects.client_version` | string | Client version (optional, from JWT claims) | +| `target` | object | Target resource information | +| `target.endpoint` | string | API endpoint path | +| `target.method` | string | MCP method called | +| `target.name` | string | Tool or resource name | +| `target.type` | string | Target type (e.g., "tool") | +| `metadata` | object | Additional metadata | +| `metadata.extra.duration_ms` | number | Operation duration in milliseconds | +| `metadata.extra.transport` | string | Transport protocol used | + +#### Audit event types + +| Event Type | Description | +| -------------------- | ------------------------- | +| `mcp_initialize` | MCP server initialization | +| `mcp_tool_call` | Tool execution request | +| `mcp_tools_list` | List available tools | +| `mcp_resource_read` | Resource access | +| `mcp_resources_list` | List available resources | +| `mcp_prompt_get` | Prompt retrieval | +| `mcp_prompts_list` | List available prompts | +| `mcp_notification` | MCP notifications | +| `mcp_ping` | Health check pings | +| `mcp_completion` | Request completion | + +(catalog entry only)"] + end + end + + Operator -.->|validates| Entry + vMCP -.->|discovers| Entry +``` + +MCPServerEntry is part of an +[MCPGroup](../reference/crd-spec.md#apiv1alpha1mcpgroup), which groups related +backend MCP servers together for vMCP discovery. When vMCP starts in +[discovered mode](../guides-vmcp/backend-discovery.mdx), it queries all +MCPServer, MCPRemoteProxy, and MCPServerEntry resources in the referenced group +and connects to them directly. + +## Prerequisites + +- A Kubernetes cluster (current and two previous minor versions are supported) +- Permissions to create resources in the cluster +- [`kubectl`](https://kubernetes.io/docs/tasks/tools/) configured to communicate + with your cluster +- The ToolHive operator installed in your cluster (see + [Deploy the operator](./deploy-operator.mdx)) +- A remote MCP server that supports HTTP transport (SSE or Streamable HTTP) + +## When to use MCPServerEntry vs. MCPRemoteProxy + +| | MCPServerEntry | MCPRemoteProxy | +| ------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | +| **Infrastructure** | No pods, services, or deployments | Creates a proxy pod and service | +| **Use case** | Lightweight catalog entries for well-known remote servers | Proxied connections requiring request transformation, caching, or the full middleware chain | +| **Discovery** | Discovered by VirtualMCPServer through MCPGroup membership | Discovered by VirtualMCPServer through MCPGroup membership | +| **Authentication** | Token exchange via `externalAuthConfigRef` | Full OIDC validation of incoming client requests | +| **Authorization** | Not applicable (no proxy layer) | Cedar policy enforcement on every request | +| **Audit logging** | Not applicable (no proxy layer) | Structured audit logs with user identity | +| **Telemetry** | Not applicable (no proxy layer) | OpenTelemetry tracing and Prometheus metrics | +| **SSRF protection** | Built-in URL validation blocks internal and metadata endpoints | N/A (proxy runs inside the cluster) | + +Choose MCPServerEntry when: + +- You trust the remote server and don't need per-request policy enforcement +- You want the simplest possible configuration with no workload resources (pods, + services, deployments) +- The remote server handles its own authentication + +Choose MCPRemoteProxy when: + +- You need to validate incoming client tokens with OIDC +- You need Cedar authorization policies on tool calls +- You need audit logging with user identity +- You need tool filtering or renaming at the proxy layer + +## Create an MCPServerEntry + +MCPServerEntry resources must be part of an MCPGroup. Create the group first if +it doesn't exist: + +```yaml title="my-group.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPGroup +metadata: + name: my-group + namespace: toolhive-system +spec: + description: Group of backend MCP servers for vMCP aggregation +``` + +Then create a basic MCPServerEntry: + +```yaml title="my-entry.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPServerEntry +metadata: + name: my-remote-tool + namespace: toolhive-system +spec: + groupRef: my-group + remoteURL: https://mcp.example.com/mcp + transport: streamable-http +``` + +Apply both resources: + +```bash +kubectl apply -f my-group.yaml -f my-entry.yaml +``` + +:::info[What's happening?] + +When you apply an MCPServerEntry resource: + +1. The ToolHive operator detects the new resource +2. The operator validates the spec: checks that the referenced MCPGroup exists, + validates the remote URL against SSRF patterns, and verifies any referenced + auth or TLS resources +3. The operator sets the entry's phase to `Valid` if all checks pass, or + `Failed` with a descriptive condition if something is wrong +4. When a VirtualMCPServer in + [discovered mode](../guides-vmcp/backend-discovery.mdx) starts, it discovers + the entry through its MCPGroup membership and connects directly to the remote + URL + +::: + +### Required fields + +| Field | Description | Validation | +| ----------- | ------------------------------------------ | -------------------------- | +| `remoteURL` | URL of the remote MCP server | Must match `^https?://` | +| `transport` | Transport protocol for the remote server | `sse` or `streamable-http` | +| `groupRef` | Name of the MCPGroup this entry belongs to | Required, minimum length 1 | + +## Configure authentication + +When the remote MCP server requires authentication, reference an +[MCPExternalAuthConfig](./token-exchange-k8s.mdx) resource to configure token +exchange. The MCPExternalAuthConfig must exist in the same namespace as the +MCPServerEntry. + +```yaml title="auth-entry.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPExternalAuthConfig +metadata: + name: my-auth-config + namespace: toolhive-system +spec: + type: tokenExchange + tokenExchange: + tokenUrl: https://auth.company.com/protocol/openid-connect/token + clientId: remote-mcp-client + clientSecretRef: + name: remote-mcp-secret + key: client-secret + audience: https://mcp.example.com +--- +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPServerEntry +metadata: + name: internal-tool + namespace: toolhive-system +spec: + groupRef: my-group + remoteURL: https://internal-mcp.corp.example.com/mcp + transport: streamable-http + # highlight-next-line + externalAuthConfigRef: + name: my-auth-config +``` + +When vMCP discovers this entry, it uses the referenced MCPExternalAuthConfig to +perform token exchange before forwarding requests to the remote server. + +## Configure custom TLS certificates + +If the remote server uses a certificate signed by an internal CA, provide a +custom CA bundle so that vMCP can verify the TLS connection. + +First, create a ConfigMap containing the CA certificate: + +```bash +kubectl create configmap internal-ca-bundle \ + --from-file=ca.crt=/path/to/ca-certificate.pem \ + -n toolhive-system +``` + +Then reference it in the MCPServerEntry: + +```yaml title="tls-entry.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPServerEntry +metadata: + name: internal-tool + namespace: toolhive-system +spec: + groupRef: my-group + remoteURL: https://internal-mcp.corp.example.com/mcp + transport: streamable-http + # highlight-start + caBundleRef: + configMapRef: + name: internal-ca-bundle + key: ca.crt + # highlight-end +``` + +## Inject custom headers + +Some remote MCP servers require custom headers for tenant identification, API +keys, or other purposes. Use the `headerForward` field to inject headers into +requests forwarded to the remote server. + +```yaml title="header-entry.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPServerEntry +metadata: + name: my-remote-tool + namespace: toolhive-system +spec: + groupRef: my-group + remoteURL: https://mcp.example.com/mcp + transport: streamable-http + # highlight-start + headerForward: + addPlaintextHeaders: + X-Custom-Header: my-value + # highlight-end +``` + +For sensitive values like API keys, use `addHeadersFromSecret` instead. See the +[Inject custom headers](./remote-mcp-proxy.mdx#inject-custom-headers) section of +the MCPRemoteProxy guide for the full syntax, which MCPServerEntry shares. + +## Complete example + +This example creates the MCPServerEntry-related resources for authentication and +custom TLS. If you reference a CA bundle ConfigMap such as `partner-ca-bundle`, +it must already exist or be created separately: + +```yaml title="complete-entry.yaml" +--- +# 1. Create the MCPGroup +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPGroup +metadata: + name: engineering-tools + namespace: toolhive-system +spec: + description: Engineering team MCP servers + +--- +# 2. Create authentication config for token exchange +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPExternalAuthConfig +metadata: + name: remote-auth + namespace: toolhive-system +spec: + type: tokenExchange + tokenExchange: + tokenUrl: https://auth.company.com/protocol/openid-connect/token + clientId: remote-mcp-client + clientSecretRef: + name: remote-mcp-secret + key: client-secret + audience: https://mcp.partner.example.com + +--- +# 3. Create the MCPServerEntry +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPServerEntry +metadata: + name: partner-tools + namespace: toolhive-system +spec: + groupRef: engineering-tools + remoteURL: https://mcp.partner.example.com/mcp + transport: streamable-http + externalAuthConfigRef: + name: remote-auth + caBundleRef: + configMapRef: + name: partner-ca-bundle + key: ca.crt + headerForward: + addPlaintextHeaders: + X-Tenant-ID: engineering +``` + +Apply all resources: + +```bash +kubectl apply -f complete-entry.yaml +``` + +## Check MCPServerEntry status + +To check the status of your entries: + +```bash +kubectl get mcpserverentries -n toolhive-system +``` + +The status shows the current phase of each entry: + +| Phase | Description | +| --------- | ------------------------------------------------------------------ | +| `Valid` | All validations passed and the entry is usable | +| `Pending` | Initial state before the first reconciliation | +| `Failed` | One or more referenced resources are missing or the URL is invalid | + +For more details about a specific entry: + +```bash +kubectl describe mcpserverentry partner-tools -n toolhive-system +``` + +Check the `Conditions` section for specific validation results: + +```bash +kubectl get mcpserverentry partner-tools -n toolhive-system -o yaml +``` + +## SSRF protection + +MCPServerEntry URLs are validated against Server-Side Request Forgery (SSRF) +patterns. The operator rejects URLs that target: + +- **Loopback addresses**: `127.0.0.0/8`, `::1` +- **Link-local addresses**: `169.254.0.0/16`, `fe80::/10` +- **Cloud metadata endpoints**: `169.254.169.254` (AWS, GCP, Azure) +- **Private network ranges**: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` + +If a URL fails SSRF validation, the entry's phase is set to `Failed` with a +condition describing the rejection reason. + +## Next steps + +- [Configure a VirtualMCPServer](../guides-vmcp/configuration.mdx) to aggregate + MCPServerEntry backends with other MCP servers +- [Set up backend discovery](../guides-vmcp/backend-discovery.mdx) to control + how vMCP finds and connects to backends +- [Configure authentication](../guides-vmcp/authentication.mdx) for + client-to-vMCP and vMCP-to-backend security + +## Related information + +- [MCPServerEntry CRD specification](../reference/crd-spec.md#apiv1alpha1mcpserverentry) - + Full MCPServerEntry field reference +- [Introduction to the Kubernetes Operator](./intro.mdx) - Overview of all + operator resource types +- [Proxy remote MCP servers](./remote-mcp-proxy.mdx) - Full-featured proxy for + remote MCP servers +- [Run MCP servers in Kubernetes](./run-mcp-k8s.mdx) - Deploy container-based + MCP servers + +## Troubleshooting + +
+ -n toolhive-system
+
+# Check operator logs
+kubectl logs -n toolhive-system -l app.kubernetes.io/name=toolhive-operator
+```
+
+Common causes:
+
+- **Operator not running**: Verify the ToolHive operator pod is healthy
+- **RBAC issues**: The operator may not have permission to reconcile
+ MCPServerEntry resources
+
+
+
+MCPServerEntry stuck in Pending phase
+ +If an MCPServerEntry remains in `Pending` phase after creation: + +```bash +# Check the entry status +kubectl describe mcpserverentry
+ -n toolhive-system \
+ -o jsonpath='{.status.conditions}' | jq
+```
+
+Common causes:
+
+- **SSRF validation failure**: The `remoteURL` targets a blocked address range
+ (loopback, link-local, private network, or cloud metadata). Use an externally
+ routable URL
+- **Missing MCPGroup**: The group referenced in `groupRef` doesn't exist. Create
+ the MCPGroup first
+- **Missing MCPExternalAuthConfig**: The auth config referenced in
+ `externalAuthConfigRef` doesn't exist in the same namespace
+- **Missing CA ConfigMap**: The ConfigMap referenced in `caBundleRef` doesn't
+ exist or the specified key is missing
+
+
+
+MCPServerEntry in Failed phase
+ +If the entry's phase is `Failed`, check the conditions for the specific reason: + +```bash +kubectl get mcpserverentry
+ -n toolhive-system \
+ -o jsonpath='{.status.discoveredBackends}' | jq
+
+# Check vMCP pod logs
+kubectl logs -n toolhive-system deployment/vmcp-
+```
+
+Common causes:
+
+- **Group mismatch**: The entry's `groupRef` doesn't match the
+ VirtualMCPServer's `config.groupRef`
+- **vMCP not restarted**: Backend changes require a pod restart to be
+ discovered. Restart the vMCP deployment:
+ ```bash
+ kubectl rollout restart deployment vmcp- -n toolhive-system
+ ```
+- **Inline mode**: The VirtualMCPServer uses `outgoingAuth.source: inline`,
+ which doesn't discover backends at runtime. Switch to `discovered` mode or add
+ the backend explicitly to `config.backends`
+
+
+
+MCPServerEntry not appearing in vMCP backends
+ +If a `Valid` MCPServerEntry doesn't appear in the VirtualMCPServer's discovered +backends: + +```bash +# Verify the entry is Valid +kubectl get mcpserverentry -n toolhive-system + +# Check the VirtualMCPServer status +kubectl get virtualmcpserver
+ | grep -i error
+```
+
+Common causes:
+
+- **TLS certificate errors**: If the remote server uses an internal CA, add a
+ `caBundleRef` pointing to the CA certificate
+- **Authentication failures**: Verify the MCPExternalAuthConfig references valid
+ credentials and the token exchange endpoint is reachable
+- **Network policies**: Ensure egress from the vMCP pod to the remote server is
+ allowed
+- **Transport mismatch**: Verify the `transport` field matches the remote
+ server's actual transport protocol
+
+
diff --git a/versioned_docs/version-1.0/toolhive/guides-k8s/quickstart.mdx b/versioned_docs/version-1.0/toolhive/guides-k8s/quickstart.mdx
new file mode 100644
index 00000000..6a4f5e33
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-k8s/quickstart.mdx
@@ -0,0 +1,485 @@
+---
+title: 'Quickstart: ToolHive Kubernetes Operator'
+sidebar_label: Quickstart
+description:
+ Learn how to deploy the ToolHive Kubernetes operator and use it to manage MCP
+ servers in a Kubernetes cluster.
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import ThemedImage from '@theme/ThemedImage';
+
+In this tutorial, you'll learn how to deploy the ToolHive Kubernetes operator
+and use it to manage MCP servers in a Kubernetes cluster. By the end, you'll
+have a working operator deployment that automatically manages MCP servers using
+Kubernetes resources.
+
+## What you'll learn
+
+- How to set up a local Kubernetes cluster with kind
+- How to deploy the ToolHive operator to your cluster
+- How to create your first MCP server using Kubernetes resources
+- How to verify that your MCP server is running correctly
+- How to connect an AI agent (like GitHub Copilot) to your MCP server
+
+## Prerequisites
+
+Before starting this tutorial, make sure you have:
+
+- [Helm](https://helm.sh/docs/intro/install/) (v3.10 minimum, v3.14+
+ recommended) installed
+- [`kubectl`](https://kubernetes.io/docs/tasks/tools/) installed
+- [Docker](https://docs.docker.com/get-docker/) or
+ [Podman](https://podman-desktop.io/downloads) installed and running
+- [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) installed
+- Basic familiarity with Kubernetes concepts (pods, deployments, services)
+- An MCP client (VS Code with Copilot is used in this tutorial, but you can use
+ any [supported client](../reference/client-compatibility.mdx))
+
+## Quickstart with Task (TL;DR)
+
+If you want to get up and running quickly and have
+[Task](https://taskfile.dev/installation/) installed, you can use our automated
+setup:
+
+1. Clone the ToolHive repository:
+
+ ```bash
+ git clone https://github.com/stacklok/toolhive.git
+ cd toolhive
+ ```
+
+2. Run the automated setup:
+
+ ```bash
+ task kind-with-toolhive-operator
+ ```
+
+This creates the kind cluster, installs an nginx ingress controller, and deploys
+the latest ToolHive operator image. You should see output indicating successful
+cluster creation and operator deployment. Once complete, skip to
+[Step 3: Create your first MCP server](#step-3-create-your-first-mcp-server) to
+continue with the tutorial.
+
+If you prefer to understand each step or don't have Task installed, continue
+with the manual setup below.
+
+## Step 1: Create a kind cluster
+
+First, create a local Kubernetes cluster using kind. This gives you a safe
+environment to experiment with the ToolHive operator.
+
+Create a cluster named `toolhive`:
+
+```bash
+kind create cluster --name toolhive
+```
+
+Verify your cluster is running:
+
+```bash
+kubectl cluster-info
+```
+
+You should see output similar to this:
+
+```text
+Kubernetes control plane is running at https://127.0.0.1:xxxxx
+CoreDNS is running at https://127.0.0.1:xxxxx/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
+```
+
+This confirms your cluster is running and ready for the ToolHive operator.
+
+:::info[What's happening?]
+
+Kind (Kubernetes in Docker) creates a local Kubernetes cluster using Docker
+containers. This is perfect for development and testing because it's isolated
+from your main system and can be easily deleted when you're done.
+
+:::
+
+## Step 2: Deploy the ToolHive operator
+
+Now deploy the ToolHive operator to your cluster using Helm. The operator will
+watch for MCP server resources and manage their lifecycle automatically.
+
+First, install the operator CRDs:
+
+```bash
+helm upgrade --install toolhive-operator-crds oci://ghcr.io/stacklok/toolhive/toolhive-operator-crds
+```
+
+Then install the operator:
+
+```bash
+helm upgrade --install toolhive-operator oci://ghcr.io/stacklok/toolhive/toolhive-operator -n toolhive-system --create-namespace
+```
+
+Verify that the operator deployed successfully:
+
+```bash
+kubectl get pods -n toolhive-system
+```
+
+You should see output similar to:
+
+```text
+NAME READY STATUS RESTARTS AGE
+toolhive-operator-xxx 1/1 Running 0 30s
+```
+
+If the pod shows "Running" status, your operator is ready to manage MCP servers.
+
+:::info[What's happening?]
+
+The ToolHive operator is a Kubernetes controller that watches for `MCPServer`
+resources. When you create an `MCPServer` resource, the operator automatically
+creates the necessary pods, services, and configurations to run that MCP server
+in your cluster.
+
+:::
+
+## Step 3: Create your first MCP server
+
+Now for the exciting part - create an MCP server using Kubernetes resources.
+You'll deploy the fetch server, which allows AI agents to retrieve web content.
+
+Apply the example `fetch` MCP server from the ToolHive repository:
+
+```bash
+kubectl apply -f https://raw.githubusercontent.com/stacklok/toolhive/refs/heads/main/examples/operator/mcp-servers/mcpserver_fetch.yaml
+```
+
+:::info[What's happening?]
+
+When you create an `MCPServer` resource, the ToolHive operator detects it and
+automatically:
+
+1. Creates a deployment to run the MCP server container
+2. Sets up a service to expose the server
+3. Configures the necessary networking and security settings
+
+:::
+
+Check that your MCP server was created successfully:
+
+```bash
+kubectl get mcpservers -n toolhive-system
+```
+
+You should see:
+
+```text
+NAME STATUS URL AGE
+fetch Running http://mcp-fetch-proxy.toolhive-system.svc.cluster.local:8080 30s
+```
+
+If the status is "Pending", wait a few moments and check again. If it remains
+pending for a long time, see the [troubleshooting section](#troubleshooting) at
+the end of this tutorial.
+
+## Step 4: Test your MCP server
+
+Verify that your MCP server is actually working. First, get the service details:
+
+```bash
+kubectl get service mcp-fetch-proxy -n toolhive-system
+```
+
+Port-forward to access the service locally:
+
+```bash
+kubectl port-forward service/mcp-fetch-proxy -n toolhive-system 8080:8080
+```
+
+In another terminal, test the server:
+
+```bash
+curl http://localhost:8080/health
+```
+
+You should see a response of `OK`.
+
+This confirms your MCP server is running and responding correctly.
+
+:::info[What's happening?]
+
+The ToolHive operator automatically creates a Kubernetes service for each MCP
+server. This service provides a stable network endpoint that other applications
+(like AI agents) can use to communicate with your MCP server.
+
+:::
+
+## Step 5: Connect your AI client to the MCP server
+
+Now that your MCP server is running in Kubernetes, connect it to an AI client
+application. We'll use Visual Studio Code with GitHub Copilot as an example.
+
+Make sure you still have the port-forward running from Step 4. If not, restart
+it in a separate terminal:
+
+```bash
+kubectl port-forward service/mcp-fetch-proxy -n toolhive-system 8080:8080
+```
+
+Configure Visual Studio Code to connect to your MCP server. Open VS Code and
+access your user settings:
+
+1. Open the command palette (Cmd/Ctrl+Shift+P)
+
+2. Type "MCP: Add Server..." and select it
+
+ Remote server connection failures
+ +If vMCP discovers the entry but can't connect to the remote server: + +```bash +# Check vMCP logs for connection errors +kubectl logs -n toolhive-system deployment/vmcp-
+
+
+Operator pod not starting
+ +If the operator pod isn't starting, check the logs: + +```bash +kubectl logs -n toolhive-system deployment/toolhive-operator +``` + +
+
+
+MCP server stuck in pending state
+ +Check the operator logs to see what's happening: + +```bash +kubectl logs -n toolhive-system deployment/toolhive-operator -f +``` + +Also check if there are any resource constraints: + +```bash +kubectl describe mcpserver fetch -n toolhive-system +``` + +
+
diff --git a/versioned_docs/version-1.0/toolhive/guides-k8s/rate-limiting.mdx b/versioned_docs/version-1.0/toolhive/guides-k8s/rate-limiting.mdx
new file mode 100644
index 00000000..cf74695f
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-k8s/rate-limiting.mdx
@@ -0,0 +1,202 @@
+---
+title: Rate limiting
+description:
+ Configure per-user and shared rate limits on MCPServer resources to prevent
+ noisy neighbors and protect downstream services.
+---
+
+Configure token bucket rate limits on MCPServer resources to control how many
+tool invocations users can make. Rate limiting prevents individual users from
+monopolizing shared servers and protects downstream services from traffic
+spikes.
+
+ToolHive supports two scopes of rate limiting:
+
+- **Shared** limits cap total requests across all users.
+- **Per-user** limits cap requests independently for each authenticated user.
+
+Both scopes can be applied at the server level and overridden per tool. A
+request must pass all applicable limits to proceed.
+
+:::info[Prerequisites]
+
+Before you begin, ensure you have:
+
+- A Kubernetes cluster with the ToolHive Operator installed
+- Redis deployed in your cluster — rate limiting stores token bucket counters in
+ Redis (see [Redis Sentinel session storage](./redis-session-storage.mdx) for
+ deployment instructions)
+- For per-user limits: authentication enabled on the MCPServer (`oidcConfig`,
+ `oidcConfigRef`, or `externalAuthConfigRef`)
+
+If you need help with these prerequisites, see:
+
+- [Kubernetes quickstart](./quickstart.mdx)
+- [Authentication and authorization](./auth-k8s.mdx)
+
+:::
+
+## How rate limiting works
+
+Rate limits use a **token bucket** algorithm. Each bucket has a capacity
+(`maxTokens`) and a refill period (`refillPeriod`). The bucket starts full and
+each `tools/call` request consumes one token. When the bucket is empty, requests
+are rejected until tokens refill. The refill rate is `maxTokens / refillPeriod`
+tokens per second.
+
+Only `tools/call` requests are rate-limited. Lifecycle methods (`initialize`,
+`ping`) and discovery methods (`tools/list`, `prompts/list`) pass through
+unconditionally.
+
+When a request is rejected, the proxy returns:
+
+- **HTTP 429** with a `Retry-After` header (seconds until a token is available)
+- A **JSON-RPC error** with code `-32029` and `retryAfterSeconds` in the error
+ data
+
+If Redis is unreachable, rate limiting **fails open** and all requests are
+allowed through.
+
+## Configure shared rate limits
+
+Shared limits apply a single token bucket across all users. Use them to cap
+total throughput to protect downstream services.
+
+```yaml title="mcpserver-shared-ratelimit.yaml"
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPServer
+metadata:
+ name: weather-server
+spec:
+ image: ghcr.io/stackloklabs/weather-mcp/server
+ transport: streamable-http
+ sessionStorage:
+ provider: redis
+ address: Can't access MCP server
+ +Verify the service is created and has endpoints: + +```bash +kubectl get service mcp-fetch-proxy -n toolhive-system +kubectl get endpoints mcp-fetch-proxy -n toolhive-system +``` + +
+
+
+Connection refused or timeout errors
+ +- Verify the Redis Sentinel pods are running: `kubectl get pods -n redis` +- Check that the Sentinel addresses in your config match the actual pod DNS + names: `kubectl get endpoints -n redis` +- Ensure network policies allow traffic from the `toolhive-system` namespace to + the `redis` namespace +- Verify the `masterName` matches the name in your Sentinel configuration + (`mymaster` in the example manifests above) + +
+
+
+ACL authentication failures
+ +- Verify the Secret exists and contains the correct credentials: + `kubectl get secret redis-acl-secret -n toolhive-system -o yaml` +- Connect to Redis directly to verify the ACL user exists: + ```bash + kubectl exec -n redis redis-0 -- redis-cli ACL LIST + ``` +- Ensure the ACL user has the required permissions (`~thv:auth:*` key pattern + and the commands listed in the ACL Secret) + +
+
+
+TLS handshake or certificate errors
+ +- Verify the CA certificate Secret exists in the `toolhive-system` namespace: + `kubectl get secret redis-ca-cert -n toolhive-system` +- Confirm the CA certificate matches the one that signed the Redis server + certificate +- Check proxy logs for TLS-specific errors: + ```bash + kubectl logs -n toolhive-system \ + -l app.kubernetes.io/name=weather-server-embedded \ + | grep -i "tls\|x509\|certificate" + ``` +- If using self-signed certificates for testing, you can set + `insecureSkipVerify: true` to bypass verification (not recommended for + production) +- When using separate Sentinel TLS, ensure both `tls` and `sentinelTls` are + configured with the correct CA certificates for their respective services + +
+
+
+## Related information
+
+- [Set up embedded authorization server authentication](./auth-k8s.mdx#set-up-embedded-authorization-server-authentication)
+- [Backend authentication](../concepts/backend-auth.mdx)
+- [Kubernetes CRD reference](../reference/crd-spec.md#apiv1alpha1authserverstorageconfig)
diff --git a/versioned_docs/version-1.0/toolhive/guides-k8s/remote-mcp-proxy.mdx b/versioned_docs/version-1.0/toolhive/guides-k8s/remote-mcp-proxy.mdx
new file mode 100644
index 00000000..f8978fe1
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-k8s/remote-mcp-proxy.mdx
@@ -0,0 +1,962 @@
+---
+title: Proxy remote MCP servers
+description:
+ How to deploy proxies for remote MCP servers in Kubernetes using the ToolHive
+ operator
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Overview
+
+The ToolHive operator can deploy proxies for remote MCP servers that are hosted
+externally. This enables you to gain centralized observability, policy
+enforcement, and audit logging for external MCP services without requiring
+changes to the remote servers themselves.
+
+Remote MCP proxies sit between your users and external MCP servers, providing:
+
+- **Authentication**: Validate user tokens using OIDC
+- **Authorization**: Apply Cedar policies based on user identity
+- **Audit logging**: Track all requests with user identity and tool information
+- **Tool filtering**: Control which tools are exposed to users
+- **Telemetry**: Collect metrics and traces for monitoring
+
+```mermaid
+flowchart LR
+ Client["Client"] -->|HTTP with token| Proxy["ToolHiveSessions lost after Redis failover
+ +- Check Sentinel logs for failover events: + `kubectl logs -n redis -l app=redis-sentinel` +- Verify that the master is reachable from Sentinel: + ```bash + kubectl exec -n redis redis-sentinel-0 -- \ + redis-cli -p 26379 SENTINEL masters + ``` +- Ensure Sentinel quorum is met (at least 2 of 3 Sentinel instances must be + running) + +Remote Proxy"] + Proxy -->|HTTP| RemoteMCP["Remote MCP Server"] + + subgraph K8s["Kubernetes Cluster"] + subgraph NS["toolhive-system"] + Operator["ToolHive Operator"] + end + subgraph NS2["Proxy Namespace"] + Proxy + end + end + + Operator -.->|creates| Proxy + + IDP["Identity Provider
(Keycloak, Okta, etc.)"] -.->|validates tokens| Proxy +``` + +:::info[Experimental] + +The MCPRemoteProxy CRD is still in an alpha state so breaking changes to the +spec and its capabilities are possible. + +::: + +## Prerequisites + +- A Kubernetes cluster (current and two previous minor versions are supported) +- Permissions to create resources in the cluster +- [`kubectl`](https://kubernetes.io/docs/tasks/tools/) configured to communicate + with your cluster +- The ToolHive operator installed in your cluster (see + [Deploy the operator](./deploy-operator.mdx)) +- An OIDC identity provider (Keycloak, Okta, Azure AD, etc.) +- Access to a remote MCP server that supports HTTP transport (SSE or Streamable + HTTP) + +## Use cases + +### Enterprise SaaS MCP servers + +Organizations using external MCP services need centralized visibility and +control over how employees interact with these services. For example, a company +using a SaaS analytics platform with an MCP interface wants to: + +- Monitor which tools employees are calling +- Apply authorization policies based on user roles +- Maintain audit logs for compliance +- Filter or restrict access to sensitive operations +- Collect centralized telemetry + +By deploying a remote MCP proxy in Kubernetes, the company gains all these +capabilities without modifying the external service. + +### Multi-tenant access control + +Different teams within an organization may need different levels of access to +the same remote MCP server. Remote proxies enable you to: + +- Deploy separate proxies with different authorization policies +- Apply team-specific tool filters +- Maintain separate audit trails per team +- Scale proxy instances independently based on team usage + +## Create a remote MCP proxy + +You can create `MCPRemoteProxy` resources in namespaces based on how the +operator was deployed. + +- **Cluster mode (default)**: Create MCPRemoteProxy resources in any namespace +- **Namespace mode**: Create MCPRemoteProxy resources only in allowed namespaces + +See [Deploy the operator](./deploy-operator.mdx#operator-deployment-modes) to +learn about the different deployment modes. + +### Basic configuration + +This example creates a remote proxy for a fictional enterprise analytics MCP +server with OIDC authentication: + +```yaml title="analytics-proxy.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPRemoteProxy +metadata: + name: analytics-proxy + namespace: toolhive-system +spec: + # Remote MCP server URL + remoteURL: https://mcp.analytics.example.com + + # Port to expose the proxy on + port: 8080 + + # Transport method (sse or streamable-http) + transport: streamable-http + + # OIDC authentication configuration + oidcConfig: + type: inline + inline: + # Your identity provider's issuer URL + issuer: https://auth.company.com/realms/production + # Expected audience claim in tokens + audience: analytics-mcp-proxy + # Optional: Client ID if using introspection + clientId: analytics-proxy + + # Authorization policies + authzConfig: + type: inline + inline: + policies: + # Allow all authenticated users to list tools + - | + permit( + principal, + action == Action::"list_tools", + resource + ); + # Allow users with 'analyst' role to call read-only tools + - | + permit( + principal, + action == Action::"call_tool", + resource + ) + when { + principal has groups && + principal.groups.contains("analyst") + }; + + # Audit logging + audit: + enabled: true + + # Resource limits + resources: + limits: + cpu: '500m' + memory: 512Mi + requests: + cpu: 100m + memory: 128Mi +``` + +Apply the resource: + +```bash +kubectl apply -f analytics-proxy.yaml +``` + +:::info[What's happening?] + +When you apply an `MCPRemoteProxy` resource, here's what happens: + +1. The ToolHive operator detects the new resource (if it's in an allowed + namespace) +2. The operator creates a Deployment running the ToolHive proxy +3. The operator creates a Service to expose the proxy +4. The proxy connects to your OIDC provider to fetch JWKS keys for token + validation +5. Clients can now connect through the proxy, which validates tokens, applies + policies, and forwards requests to the remote MCP server + +::: + +### Authentication configuration + +The `oidcConfig` field validates incoming tokens from users. The proxy supports +multiple authentication methods: + +
+
+
+Proxy pod in CrashLoopBackOff
+ +If the proxy pod is restarting continuously: + +```bash +# Check pod status +kubectl get pods -n toolhive-system -l app.kubernetes.io/instance=analytics-proxy + +# Check pod logs +kubectl logs -n toolhive-system -l app.kubernetes.io/instance=analytics-proxy +``` + +Common causes: + +- **Invalid OIDC configuration**: Verify the issuer URL is accessible and + returns valid OIDC discovery metadata +- **Certificate validation issues**: If using a custom CA, ensure + `thvCABundlePath` is set correctly +- **Resource limits**: Check if the pod has sufficient CPU and memory + +
+" | cut -d. -f2 | tr '_-' '/+' | awk '{l=length($0)%4; if(l>0) printf "%s", substr("====",1,4-l); print $0}' | base64 -d 2>/dev/null | jq
+```
+
+:::note
+
+JWTs use base64url encoding and may omit padding characters (`=`). The command
+above converts base64url to standard base64 and adds padding if needed. If you
+get an "invalid input" error, check your shell and base64 version, or manually
+add padding to the payload.
+
+:::
+
+
+
+401 Unauthorized errors
+ +If clients receive 401 errors when calling the proxy: + +```bash +# Check proxy logs for authentication errors +kubectl logs -n toolhive-system -l app.kubernetes.io/instance=analytics-proxy | grep -i "auth" +``` + +Common causes: + +- **Missing audience claim**: Ensure tokens include the expected `aud` claim +- **Token expired**: Check token expiration time +- **Issuer mismatch**: Verify token `iss` claim matches `oidcConfig.issuer` +- **JWKS fetch failure**: Check proxy can reach the OIDC provider's JWKS + endpoint + +Verify your token claims: + +```bash +# Decode JWT payload (requires jq) +# This handles base64url and missing padding +echo "
+ -- \
+ curl -v https://mcp.analytics.example.com
+```
+
+Common causes:
+
+- **Network policies**: Check if network policies allow egress to the remote
+ server
+- **DNS resolution**: Verify the remote URL resolves correctly
+- **Firewall rules**: Ensure the cluster can reach the remote server
+- **Certificate issues**: If using HTTPS, verify certificates are valid
+
+
+
+Remote server unreachable
+ +If the proxy cannot connect to the remote MCP server: + +```bash +# Check proxy logs +kubectl logs -n toolhive-system -l app.kubernetes.io/instance=analytics-proxy + +# Test connectivity from the pod +kubectl exec -n toolhive-system
+
+
+Tool filtering not working
+ +If tool filtering isn't being applied: + +```bash +# Check if MCPToolConfig exists +kubectl get mcptoolconfig -n toolhive-system + +# Verify the reference in MCPRemoteProxy +kubectl get mcpremoteproxy analytics-proxy -n toolhive-system -o yaml | \ + grep -A2 toolConfigRef +``` + +Ensure: + +- The MCPToolConfig exists in the same namespace as the MCPRemoteProxy +- The `toolConfigRef.name` matches the MCPToolConfig name +- The MCPRemoteProxy status shows the config is applied + +
+
+
+Token exchange failing
+ +If token exchange is configured but not working: + +```bash +# Check for token exchange errors in logs +kubectl logs -n toolhive-system -l app.kubernetes.io/instance=analytics-proxy | \ + grep -i "token.*exchange" +``` + +Verify: + +- The MCPExternalAuthConfig exists and is correctly configured +- The client secret is valid and stored in a Kubernetes Secret +- The token exchange endpoint is reachable from the proxy +- The company IDP is configured for token exchange (RFC 8693) + +
+
diff --git a/versioned_docs/version-1.0/toolhive/guides-k8s/run-mcp-k8s.mdx b/versioned_docs/version-1.0/toolhive/guides-k8s/run-mcp-k8s.mdx
new file mode 100644
index 00000000..339d6f9c
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-k8s/run-mcp-k8s.mdx
@@ -0,0 +1,689 @@
+---
+title: Run MCP servers in Kubernetes
+description: How to deploy MCP servers in Kubernetes using the ToolHive operator
+---
+
+## Prerequisites
+
+- A Kubernetes cluster (current and two previous minor versions are supported)
+- Permissions to create resources in the cluster
+- [`kubectl`](https://kubernetes.io/docs/tasks/tools/) configured to communicate
+ with your cluster
+- The ToolHive operator installed in your cluster (see
+ [Deploy the operator](./deploy-operator.mdx))
+
+## Overview
+
+The ToolHive operator deploys MCP servers in Kubernetes by creating proxy pods
+that manage the actual MCP server containers.
+
+:::tip
+
+If you need to build a container image for an MCP server that doesn't already
+have one available, see the
+[Build MCP containers](../guides-cli/build-containers.mdx) guide to learn how to
+quickly create container images using the ToolHive CLI.
+
+:::
+
+### High-level architecture
+
+This diagram shows the basic relationship between components. The ToolHive
+operator watches for `MCPServer` resources and automatically creates the
+necessary infrastructure to run your MCP servers securely within the cluster.
+
+```mermaid
+flowchart LR
+ Client["Client"] -->|connects| Proxy["ToolHiveGetting more debug information
+ +For additional debugging: + +```bash +# Get all resources related to your proxy +kubectl get all -n toolhive-system -l app.kubernetes.io/instance=analytics-proxy + +# Export MCPRemoteProxy for inspection +kubectl get mcpremoteproxy analytics-proxy -n toolhive-system -o yaml + +# Check operator logs +kubectl logs -n toolhive-system -l app.kubernetes.io/name=toolhive-operator + +# Check events +kubectl get events -n toolhive-system --sort-by='.lastTimestamp' | \ + grep analytics-proxy +``` + +Proxy/Runner"] + Proxy --> MCP["MCP Server"] + + subgraph K8s["Kubernetes Cluster"] + subgraph NS["toolhive-system"] + Operator["ToolHive Operator"] + end + subgraph NS2["MCP Server
Namespace"] + Proxy + MCP + end + end + + Operator -.->|creates| Proxy + Proxy -.->|creates| MCP +``` + +### STDIO transport flow + +For MCP servers using STDIO transport, the proxy directly attaches to the MCP +server pod's standard input/output streams. + +```mermaid +flowchart LR + subgraph Proxy["Created by Operator"] + direction TB + ProxyService["SVC: ToolHive-Proxy"] + ProxyPod["POD: ToolHive-Proxy"] + ProxyService --> ProxyPod + end + + subgraph MCP["Created by Proxy"] + direction TB + MCPPod["POD: MCP Server"] + end + + Client["Client"] -->|HTTP/SSE| Proxy + Proxy -->|Attaches/STDIO| MCP +``` + +:::info[STDIO Transport Limitation] + +MCP servers using STDIO transport support only a single client connection at a +time. If you need to support multiple users or concurrent client connections, +use SSE (Server-Sent Events) or Streamable HTTP transport instead. + +::: + +### Streamable HTTP and SSE transport flow + +For MCP servers using Server-Sent Events (SSE) or Streamable HTTP transport, the +proxy creates both a pod and a headless service. This allows direct HTTP/SSE or +HTTP/Streamable HTTP communication between the proxy and MCP server while +maintaining network isolation and service discovery. + +```mermaid +flowchart LR + subgraph Proxy["Created by Operator"] + direction TB + ProxyService["SVC: ToolHive-Proxy"] + ProxyPod["POD: ToolHive-Proxy"] + ProxyService --> ProxyPod + end + + subgraph MCP["Created by Proxy"] + direction TB + MCPService["SVC: MCP-Headless"] + MCPPod["POD: MCP Server"] + end + + Client["Client"] -->|HTTP| Proxy + Proxy -->|HTTP| MCP + MCPService --> MCPPod +``` + +## Create an MCP server + +You can create `MCPServer` resources in namespaces based on how the operator was +deployed. + +- **Cluster mode (default)**: Create MCPServer resources in any namespace +- **Namespace mode**: Create MCPServer resources only in allowed namespaces + +See [Deploy the operator](./deploy-operator.mdx#operator-deployment-modes) to +learn about the different deployment modes. + +To create an MCP server, define an `MCPServer` resource and apply it to your +cluster. This minimal example creates the +[`osv` MCP server](https://github.com/StacklokLabs/osv-mcp) which queries the +[Open Source Vulnerability (OSV) database](https://osv.dev/) for vulnerability +information. + +```yaml title="my-mcpserver.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPServer +metadata: + name: osv + namespace: my-namespace # Update with your namespace +spec: + image: ghcr.io/stackloklabs/osv-mcp/server + transport: streamable-http + mcpPort: 8080 + proxyPort: 8080 + resources: + limits: + cpu: '100m' + memory: '128Mi' + requests: + cpu: '50m' + memory: '64Mi' +``` + +Apply the resource: + +```bash +kubectl apply -f my-mcpserver.yaml +``` + +:::info[What's happening?] + +When you apply an `MCPServer` resource, here's what happens: + +1. The ToolHive operator detects the new resource (if it's in an allowed + namespace) +2. The operator automatically creates the necessary RBAC resources in the target + namespace: + - A ServiceAccount with the same name as the MCPServer + - A Role with minimal permissions for StatefulSets, Services, Pods, and Pod + logs/attach operations + - A RoleBinding that connects the ServiceAccount to the Role +3. The operator creates a new Deployment containing a ToolHive proxy pod and + service to handle client connections +4. The proxy creates the actual `MCPServer` pod containing your specified + container image +5. For STDIO transport, the proxy attaches directly to the pod; for SSE and + Streamable HTTP transport, a headless service is created for direct pod + communication +6. Clients can now connect through the service → proxy → MCP server chain to use + the tools and resources (note: external clients will need an ingress + controller or similar mechanism to access the service from outside the + cluster) + +::: + +For more examples of `MCPServer` resources, see the +[example MCP server manifests](https://github.com/stacklok/toolhive/tree/main/examples/operator/mcp-servers) +in the ToolHive repo. + +## Automatic RBAC management + +The ToolHive operator automatically handles RBAC (Role-Based Access Control) for +each MCPServer instance, providing better security isolation and multi-tenant +support. Here's what the operator creates automatically: + +- **ServiceAccount**: A dedicated ServiceAccount with the same name as your + MCPServer +- **Role**: A namespace-scoped Role with minimal permissions for: + - StatefulSets (create, get, list, watch, update, patch, delete) + - Services (create, get, list, watch, update, patch, delete) + - Pods (get, list, watch) + - Pod logs and attach operations (get, list) +- **RoleBinding**: Connects the ServiceAccount to the Role + +This approach provides: + +- Each MCPServer operates with its own minimal set of permissions +- No manual RBAC setup required +- Better security isolation between different MCPServer instances +- Support for multi-tenant deployments across different namespaces + +## Customize server settings + +You can customize the MCP server by adding additional fields to the `MCPServer` +resource. The full specification is available in the +[Kubernetes CRD reference](../reference/crd-spec.md#apiv1alpha1mcpserver). + +Below are some common configurations. + +### Customize the MCP server pod + +You can customize the MCP server pod that gets created by the proxy using the +`podTemplateSpec` field. This gives you full control over the pod specification, +letting you set security contexts, resource limits, node selectors, and other +pod-level configurations. + +The `podTemplateSpec` field follows the standard Kubernetes +[`PodTemplateSpec`](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-template-v1/#PodTemplateSpec) +format, so you can use any valid pod specification options. + +This example sets resource limits. + +```yaml {14-15} title="my-mcpserver-custom-pod.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPServer +metadata: + name: fetch + namespace: development # Can be any namespace +spec: + image: ghcr.io/stackloklabs/gofetch/server + transport: streamable-http + mcpPort: 8080 + proxyPort: 8080 + podTemplateSpec: + spec: + containers: + - name: mcp # This name must be "mcp" + resources: # These resources apply to the MCP container + limits: + cpu: '500m' + memory: '512Mi' + requests: + cpu: '100m' + memory: '128Mi' + resources: # These resources apply to the proxy container + limits: + cpu: '100m' + memory: '128Mi' + requests: + cpu: '50m' + memory: '64Mi' +``` + +:::info[Container name requirement] + +When customizing containers in `podTemplateSpec`, you must use `name: mcp` for +the main container. This ensures the proxy can properly manage the MCP server +process. + +::: + +### Run a server with secrets + +When your MCP servers require authentication tokens or other secrets, ToolHive +supports multiple secrets management methods to fit your existing +infrastructure. Choose the method that best suits your needs: + +
+ describe mcpserver
+
+# Check operator logs
+kubectl -n toolhive-system logs -l app.kubernetes.io/name=toolhive-operator
+
+# Verify the operator is running
+kubectl -n toolhive-system get pods -l app.kubernetes.io/name=toolhive-operator
+```
+
+Other common causes include:
+
+- **Operator not running**: Ensure the ToolHive operator is deployed and running
+- **Invalid image reference**: Verify the container image exists and is
+ accessible
+- **RBAC issues**: The operator automatically creates RBAC resources, but check
+ for cluster-level permission issues
+- **Resource quotas**: Check if namespace resource quotas prevent pod creation
+
+
+
+MCPServer resource not creating pods
+ +If your `MCPServer` resource is created but no pods appear, first ensure you +created the `MCPServer` resource in an allowed namespace. If the operator runs +in namespace mode and you didn't include the namespace in the +`allowedNamespaces` list, the operator ignores the resource. Check the +operator's configuration: + +```bash +helm get values toolhive-operator -n toolhive-system +``` + +Check the `operator.rbac.scope` and `operator.rbac.allowedNamespaces` +properties. If the operator runs in `namespace` mode, add the namespace where +you created the `MCPServer` to the `allowedNamespaces` list. See +[Operator deployment modes](./deploy-operator.mdx#operator-deployment-modes). + +If the operator runs in `cluster` mode (default) or the `MCPServer` is in an +allowed namespace, check the operator logs and resource status: + +```bash +# Check MCPServer status +kubectl -n
+ get pods
+
+# Describe the failing pod
+kubectl -n describe pod
+
+# Check pod logs
+kubectl -n logs -c mcp
+```
+
+Common causes include:
+
+- **Image pull errors**: Verify the container image is accessible and the image
+ name is correct
+- **Missing secrets**: Ensure required secrets exist and are properly referenced
+- **Resource constraints**: Check if the pod has sufficient CPU and memory
+ resources
+- **Permission issues**: Verify the security context and RBAC permissions are
+ correctly configured
+- **Invalid arguments**: Check if the `args` field contains valid arguments for
+ the MCP server
+
+
+
+MCP server pod fails to start
+ +If the MCP server pod is created but fails to start or is in `CrashLoopBackOff`: + +```bash +# Check pod status +kubectl -n
+ get pods -l app.kubernetes.io/instance=
+
+# Check proxy logs
+kubectl -n logs -l app.kubernetes.io/instance=
+
+# Verify service is created
+kubectl -n get services
+```
+
+Common causes include:
+
+- **Service not created**: Ensure the proxy service exists and has the correct
+ selectors
+- **Port configuration**: Verify the `port` field matches the MCP server's
+ listening port
+- **Transport mismatch**: Ensure the `transport` field
+ (stdio/sse/streamable-http) matches the MCP server's capabilities
+- **Network policies**: Check if network policies are blocking communication
+
+
+
+Proxy pod connection issues
+ +If the proxy pod is running but clients cannot connect: + +```bash +# Check proxy pod status +kubectl -n
+ get secret
+
+# Verify secret content
+kubectl -n describe secret
+
+# Check environment variables in the pod
+kubectl -n exec -c mcp -- env | grep
+```
+
+Common causes include:
+
+- **Secret doesn't exist**: Create the secret in the correct namespace
+- **Wrong key name**: Ensure the `key` field matches the actual key in the
+ secret
+- **Namespace mismatch**: Secrets must be in the same namespace as the
+ `MCPServer`
+- **Permission issues**: The operator automatically creates the necessary RBAC
+ resources, but verify the ServiceAccount has access to read secrets
+
+
+
+Secret mounting issues
+ +If secrets are not being properly mounted or environment variables are missing: + +```bash +# Check if secret exists +kubectl -n
+ get pvc
+
+# Describe the PVC
+kubectl -n describe pvc
+
+# Check volume mounts in the pod
+kubectl -n describe pod
+```
+
+Common causes include:
+
+- **PVC not bound**: Ensure the PersistentVolumeClaim is bound to a
+ PersistentVolume
+- **Namespace mismatch**: The PVC must be in the same namespace as the MCPServer
+- **Storage class issues**: Verify the storage class exists and is available
+- **Access mode conflicts**: Check that the access mode is compatible with your
+ setup
+- **Mount path conflicts**: Ensure mount paths don't conflict with existing
+ directories
+
+
+
+Volume mounting problems
+ +If persistent volumes or other volumes are not mounting correctly: + +```bash +# Check PVC status +kubectl -n
+ top pods
+
+# Check for resource limit events
+kubectl -n get events --sort-by='.lastTimestamp'
+
+# Describe the pod for resource information
+kubectl -n describe pod
+```
+
+Solutions:
+
+- **Increase resource limits**: Adjust `resources.limits` in the `MCPServer`
+ spec
+- **Optimize resource requests**: Set appropriate `resources.requests` values
+- **Check node capacity**: Ensure cluster nodes have sufficient resources
+- **Review resource quotas**: Check namespace resource quotas and limits
+
+
+
+Resource limit issues
+ +If pods are being killed due to resource constraints: + +```bash +# Check resource usage +kubectl -n
+ port-forward service/ 8080:8080
+
+# Test the connection locally
+curl http://localhost:8080/health
+
+# Check service endpoints
+kubectl -n get endpoints
+```
+
+
+
+Debugging connectivity
+ +To test connectivity between components: + +```bash +# Port-forward to test direct access to the proxy +kubectl -n
+ get all -l app.kubernetes.io/instance=
+
+# Check operator events
+kubectl -n get events --field-selector involvedObject.kind=MCPServer
+
+# Export MCPServer resource for inspection
+kubectl -n get mcpserver -o yaml
+```
+
+
diff --git a/versioned_docs/version-1.0/toolhive/guides-k8s/telemetry-and-metrics.mdx b/versioned_docs/version-1.0/toolhive/guides-k8s/telemetry-and-metrics.mdx
new file mode 100644
index 00000000..5fb2d452
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-k8s/telemetry-and-metrics.mdx
@@ -0,0 +1,286 @@
+---
+title: Telemetry and metrics
+description: How to enable OpenTelemetry (metrics and traces) and Prometheus
+ instrumentation for ToolHive MCP servers inside of Kubernetes using the
+ ToolHive Operator
+---
+
+ToolHive includes built-in instrumentation using OpenTelemetry, which gives you
+comprehensive observability for your MCP server interactions. You can export
+traces and metrics to popular observability backends like Jaeger, Honeycomb,
+Datadog, and Grafana Cloud, or expose Prometheus metrics directly.
+
+## What you can monitor
+
+ToolHive's telemetry captures detailed information about MCP interactions
+including traces, metrics, and performance data. For a comprehensive overview of
+the telemetry architecture, metrics collection, and monitoring capabilities, see
+the [observability overview](../concepts/observability.mdx).
+
+## Enable telemetry
+
+You can enable telemetry when deploying an MCP server by specifying Telemetry
+configuration in the MCPServer or MCPRemoteProxy custom resource.
+
+This example runs the Fetch MCP server and exports traces to a deployed instance
+of the [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/):
+
+```yaml {12}
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: MCPServer # or MCPRemoteProxy
+metadata:
+ name: gofetch
+ namespace: toolhive-system
+spec:
+ image: ghcr.io/stackloklabs/gofetch/server
+ transport: streamable-http
+ proxyPort: 8080
+ mcpPort: 8080
+ # ... other spec fields ...
+ telemetry:
+ openTelemetry:
+ enabled: true
+ endpoint: otel-collector-opentelemetry-collector.monitoring.svc.cluster.local:4318
+ serviceName: mcp-fetch-server
+ insecure: true
+ metrics:
+ enabled: true
+ tracing:
+ enabled: true
+ samplingRate: '0.05'
+ prometheus:
+ enabled: true
+```
+
+The `spec.telemetry.openTelemetry.endpoint` will be the OpenTelemetry collector
+that is deployed inside of your infrastructure, the
+`spec.telemetry.openTelemetry.serviceName` will be what you can use to identify
+your MCP server in your observability stack.
+
+### Export metrics to an OTLP endpoint
+
+If you want to enable ToolHive to export metrics to your OTel collector, you can
+enable the `spec.telemetry.openTelemetry.metrics.enabled` flag.
+
+### Export traces to an OTLP endpoint
+
+If you want to enable ToolHive to export tracing information, you can enable the
+`spec.telemetry.openTelemetry.tracing.enabled` flag.
+
+You can also set the sampling rate of your traces by setting the
+`spec.telemetry.openTelemetry.tracing.sampleRate` option to a number between 0
+and 1.0. By default this will be `0.05` which equates to 5% of all requests.
+
+:::note
+
+The `spec.telemetry.openTelemetry.endpoint` is provided as a hostname and
+optional port, without a scheme or path (e.g., use `api.honeycomb.io` or
+`api.honeycomb.io:443`, not `https://api.honeycomb.io`). ToolHive automatically
+uses HTTPS unless `--otel-insecure` is specified.
+
+:::
+
+By default, the service name is set to `toolhive-mcp-proxy`, and the sampling
+rate is `0.05` (5%).
+
+:::tip[Recommendation]
+
+Set the `spec.telemetry.openTelemetry.serviceName` flag to a meaningful name for
+each MCP server. This helps you identify the server in your observability
+backend.
+
+:::
+
+### Enable Prometheus metrics
+
+You can expose Prometheus-style metrics at `/metrics` on the main transport port
+for local scraping by enabling the `spec.telemetry.prometheus.enabled` flag.
+
+To access the metrics, you can use `curl` or any Prometheus-compatible scraper.
+The metrics are available at `http://Getting more debug information
+ +For additional debugging information: + +```bash +# Get all resources related to your MCP server +kubectl -n
+
+OAuth authentication fails
+ +If OAuth authentication fails or times out: + +1. Ensure the callback port is not blocked by a firewall +2. Check that your browser allows pop-ups from ToolHive +3. Try restarting the server with `thv restart notion-remote` + +
+
+Server shows "Running" but tools don't work
+ +The server may have lost authentication. Restart the server to re-authenticate: + +```bash +thv restart notion-remote +``` + +
+
+Can't find content in search results
+ +- Notion search uses semantic search, which may return different results than + exact keyword matching +- Try using more specific search terms or filtering by page, database, or + teamspace +- Check that you have access to the content you're searching for (permissions + may limit results) + +
+
diff --git a/versioned_docs/version-1.0/toolhive/guides-mcp/osv.mdx b/versioned_docs/version-1.0/toolhive/guides-mcp/osv.mdx
new file mode 100644
index 00000000..50e65b7a
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-mcp/osv.mdx
@@ -0,0 +1,121 @@
+---
+title: OSV MCP server guide
+sidebar_label: Open Source Vulnerabilities (OSV)
+description: Using the Open Source Vulnerabilities database (OSV) MCP server with ToolHive.
+last_update:
+ author: danbarr
+ date: 2026-02-10
+---
+
+## Overview
+
+The [OSV MCP server](https://github.com/StacklokLabs/osv-mcp) provides access to
+the [Open Source Vulnerabilities database](https://osv.dev), which aggregates
+vulnerability data from multiple sources including GitHub Security Advisories,
+PyPA, RustSec, and many others. This server enables AI agents to:
+
+- Query vulnerabilities for specific package versions or Git commits
+- Perform batch vulnerability queries across multiple packages
+- Retrieve detailed vulnerability information by OSV ID
+- Access comprehensive vulnerability data including severity, affected versions,
+ and remediation guidance
+
+The server supports various package ecosystems including npm, PyPI, Go modules,
+Maven, NuGet, and more, making it an essential tool for security analysis and
+dependency management workflows.
+
+## Metadata
+
+Rate limits
+ +Notion's API has rate limits. If you encounter rate limit errors: + +- Reduce the frequency of requests +- Use more specific queries to reduce the amount of data retrieved +- Wait for the rate limit to reset (typically a few minutes) + +Namespace"] + Registry["Registry Server"] + DB[("PostgreSQL")] + end + subgraph Sources["Registry Sources"] + Git["Git Repository"] + CM["ConfigMap"] + PVC["PVC"] + API["Upstream API"] + end + end + + Operator -.->|creates| Registry + Sources -->|sync| Registry + Registry --> DB +``` + +## Create a registry + +You can create `MCPRegistry` resources in the namespaces where the ToolHive +Operator is deployed. + +See +[Deploy the operator](../guides-k8s/deploy-operator.mdx#operator-deployment-modes) +to learn about the different deployment modes. + +To create a registry, define an `MCPRegistry` resource and apply it to your +cluster. This minimal example creates a registry that syncs from the ToolHive +Git repository. + +```yaml title="my-registry.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPRegistry +metadata: + name: my-registry + namespace: my-namespace # Update with your namespace +spec: + displayName: My MCP Registry + auth: + mode: anonymous + registries: + - name: toolhive + format: toolhive + git: + repository: https://github.com/stacklok/toolhive-catalog.git + branch: main + path: pkg/catalog/toolhive/data/registry.json + syncPolicy: + interval: '30m' +``` + +Apply the resource: + +```bash +kubectl apply -f my-registry.yaml +``` + +:::info[What's happening?] + +When you apply an `MCPRegistry` resource, here's what happens: + +1. The ToolHive operator detects the new resource (if it's in an allowed + namespace) +2. The operator creates the necessary RBAC resources in the target namespace +3. The operator creates a Deployment containing the Registry server pod and + service +4. The Registry server syncs data from the configured sources +5. The Registry API becomes available at the service endpoint + +::: + +## Configuring source Registries + +The `MCPRegistry` resource supports multiple registry source types. You can +configure one or more of them. Each type is mutually exclusive within a single +registry configuration. + +### Git repository source + +Clone and sync from Git repositories. Ideal for version-controlled registries. + +```yaml {9-14} title="registry-git.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPRegistry +metadata: + name: git-registry +spec: + auth: + mode: anonymous + registries: + - name: toolhive + format: toolhive + git: + repository: https://github.com/stacklok/toolhive-catalog.git + branch: main + path: pkg/catalog/toolhive/data/registry.json + syncPolicy: + interval: '30m' +``` + +**Git source fields:** + +| Field | Required | Description | +| ------------ | -------- | ----------------------------------------------------- | +| `repository` | Yes | Git repository URL (HTTP/HTTPS/SSH) | +| `branch` | No | Branch name (mutually exclusive with `tag`, `commit`) | +| `tag` | No | Tag name (mutually exclusive with `branch`, `commit`) | +| `commit` | No | Commit SHA (mutually exclusive with `branch`, `tag`) | +| `path` | No | Path to registry file (default: `registry.json`) | + +:::tip + +You can use `branch`, `tag`, or `commit` to pin to a specific version. If +multiple are specified, `commit` takes precedence over `tag`, which takes +precedence over `branch`. + +::: + +### ConfigMap source + +Read from a Kubernetes ConfigMap. Ideal for registry data managed within the +cluster. + +```yaml {7-11} title="registry-configmap.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPRegistry +metadata: + name: configmap-registry +spec: + auth: + mode: anonymous + registries: + - name: local + format: upstream + configMapRef: + name: registry-data + key: registry.json + syncPolicy: + interval: '15m' +``` + +The ConfigMap must exist in the same namespace as the `MCPRegistry` resource. + +### PersistentVolumeClaim source + +Read from a PersistentVolumeClaim. Useful for large registry files or shared +storage scenarios. + +```yaml {7-10} title="registry-pvc.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPRegistry +metadata: + name: pvc-registry +spec: + auth: + mode: anonymous + registries: + - name: shared + format: upstream + pvcRef: + claimName: registry-data-pvc + path: registries/production.json + syncPolicy: + interval: '1h' +``` + +**PVC source fields:** + +| Field | Required | Description | +| ----------- | -------- | ----------------------------------------------------------- | +| `claimName` | Yes | Name of the PersistentVolumeClaim | +| `path` | No | Path to registry file within PVC (default: `registry.json`) | + +The PVC must exist in the same namespace as the `MCPRegistry` resource. + +### API source + +Sync from an upstream MCP Registry API. Supports federation and aggregation +scenarios. + +```yaml {7-10} title="registry-api.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPRegistry +metadata: + name: api-registry +spec: + auth: + mode: anonymous + registries: + - name: upstream + format: upstream + api: + endpoint: https://registry.example.com + syncPolicy: + interval: '1h' +``` + +The controller automatically appends the appropriate API paths to the endpoint +URL. + +### Configure synchronization + +Each registry source can have its own sync policy that controls automatic +synchronization. + +```yaml +syncPolicy: + interval: '30m' # Go duration format: "1h", "30m", "24h" +``` + +### Filter registry content + +You can filter which servers are exposed through the API using name and tag +patterns. + +```yaml {13-20} title="registry-filtered.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPRegistry +metadata: + name: filtered-registry +spec: + auth: + mode: anonymous + registries: + - name: toolhive + format: toolhive + git: + repository: https://github.com/stacklok/toolhive-catalog.git + branch: main + path: pkg/catalog/toolhive/data/registry.json + filter: + names: + include: + - 'official/*' + exclude: + - '*/deprecated' + tags: + include: + - production + exclude: + - experimental + syncPolicy: + interval: '30m' +``` + +## Configure database storage + +Configure PostgreSQL database storage for the Registry server. + +```yaml {17-32} title="registry-with-database.yaml" +apiVersion: v1 +kind: Secret +metadata: + name: registry-api-db-passwords +type: Opaque +stringData: + db-password: app_password + migration-password: migrator_password +--- +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPRegistry +metadata: + name: production-registry +spec: + auth: + mode: anonymous + databaseConfig: + host: postgres.database.svc.cluster.local + port: 5432 + user: db_app + migrationUser: db_migrator + dbAppUserPasswordSecretRef: + name: registry-api-db-passwords + key: db-password + dbMigrationUserPasswordSecretRef: + name: registry-api-db-passwords + key: migration-password + database: registry + sslMode: verify-full + maxOpenConns: 25 + maxIdleConns: 5 + connMaxLifetime: '30m' + registries: + - name: toolhive + format: toolhive + git: + repository: https://github.com/stacklok/toolhive-catalog.git + branch: main + path: pkg/catalog/toolhive/data/registry.json + syncPolicy: + interval: '30m' +``` + +**Database configuration fields:** + +| Field | Default | Description | +| ---------------------------------- | ------------- | ------------------------------------------------- | +| `host` | `postgres` | Database server hostname | +| `port` | `5432` | Database server port | +| `user` | `db_app` | Application user (SELECT, INSERT, UPDATE, DELETE) | +| `migrationUser` | `db_migrator` | Migration user (CREATE, ALTER, DROP) | +| `dbAppUserPasswordSecretRef` | `` | Password of application user | +| `dbMigrationUserPasswordSecretRef` | `` | Password of migration user | +| `database` | `registry` | Database name | +| `sslMode` | `prefer` | SSL mode (disable, prefer, require, verify-full) | +| `maxOpenConns` | `10` | Maximum open connections | +| `maxIdleConns` | `2` | Maximum idle connections | +| `connMaxLifetime` | `30m` | Maximum connection lifetime | + +:::tip + +Credentials are internally configured using a pgpass file mounted as a secret. + +::: + +## Configure authentication + +You can configure authentication using the `authConfig` field in your +`MCPRegistry` resource. + +### Authentication modes + +| Mode | Description | Use case | +| ----------- | ----------------------------------------------- | ---------------------------- | +| `oauth` | Validates access tokens from identity providers | Production deployments | +| `anonymous` | No authentication required | Development and testing only | + +:::info[Secure by default] + +Configuring an authentication mode is mandatory, if you're not interested you +can set it to `anonymous`. + +::: + +### OAuth authentication + +OAuth mode validates JWT tokens from one or more identity providers. Configure +providers in the `authConfig.oauth.providers` array. + +```yaml title="registry-oauth.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPRegistry +metadata: + name: registry + namespace: toolhive-system +spec: + displayName: 'Authenticated MCP Server Registry' + authConfig: + mode: oauth + oauth: + providers: + - name: kubernetes + issuerUrl: https://kubernetes.default.svc.cluster.local + jwksUrl: https://kubernetes.default.svc/openid/v1/jwks + audience: registry-server + caCertPath: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt + authTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token + allowPrivateIP: true + registries: + - name: toolhive + format: toolhive + git: + repository: https://github.com/stacklok/toolhive-catalog.git + branch: main + path: pkg/catalog/toolhive/data/registry.json +``` + +### OAuth configuration fields + +| Field | Required | Default | Description | +| ----------------- | -------- | ----------------------------------------- | -------------------------------------------------- | +| `mode` | No | `oauth` | Authentication mode (`oauth` or `anonymous`) | +| `resourceUrl` | No | - | URL identifying this protected resource (RFC 9728) | +| `realm` | No | `mcp-registry` | Protection space identifier for WWW-Authenticate | +| `scopesSupported` | No | `[mcp-registry:read, mcp-registry:write]` | OAuth scopes supported by this resource | + +### Provider configuration fields + +| Field | Required | Description | +| ------------------ | -------- | ----------------------------------------------------------------------- | +| `name` | Yes | Unique identifier for this provider (for logging and monitoring) | +| `issuerUrl` | Yes | OIDC issuer URL (e.g., `https://accounts.google.com`) | +| `audience` | Yes | Expected audience claim in the access token | +| `jwksUrl` | No | JWKS endpoint URL (skips OIDC discovery if specified) | +| `clientId` | No | OAuth client ID for token introspection | +| `clientSecretFile` | No | Path to file containing the client secret | +| `caCertPath` | No | Path to CA certificate for TLS verification | +| `authTokenFile` | No | Path to token file for authenticating to OIDC/JWKS endpoints | +| `introspectionUrl` | No | Token introspection endpoint URL for opaque token validation (RFC 7662) | +| `allowPrivateIP` | No | Allow connections to private IP addresses (required for in-cluster) | + +### Kubernetes service account authentication + +For in-cluster deployments, you can configure OAuth to validate Kubernetes +service account tokens: + +```yaml title="registry-k8s-auth.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPRegistry +metadata: + name: registry +spec: + authConfig: + mode: oauth + oauth: + providers: + - name: kubernetes + issuerUrl: https://kubernetes.default.svc.cluster.local + jwksUrl: https://kubernetes.default.svc/openid/v1/jwks + audience: registry-server + caCertPath: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt + authTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token + allowPrivateIP: true +``` + +:::tip[Kubernetes provider settings] + +- **issuerUrl**: for most Kubernetes distributions, + `https://kubernetes.default.svc.cluster.local` is the correct value to match + the `iss` claim in Kubernetes service account tokens. +- **jwksUrl**: Specify directly to skip OIDC discovery (the Kubernetes API + server doesn't support standard discovery). +- **allowPrivateIP**: Required for in-cluster communication with the API server. + +::: + +### Multiple providers + +You can configure multiple OAuth providers to accept tokens from different +identity sources: + +```yaml title="registry-multi-provider.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPRegistry +metadata: + name: registry +spec: + authConfig: + mode: oauth + oauth: + providers: + # Kubernetes service accounts (in-cluster workloads) + - name: kubernetes + issuerUrl: https://kubernetes.default.svc.cluster.local + jwksUrl: https://kubernetes.default.svc/openid/v1/jwks + audience: registry-server + caCertPath: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt + authTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token + allowPrivateIP: true + # External identity provider + - name: okta + issuerUrl: https://YOUR_DOMAIN.okta.com/oauth2/default + audience: registry +``` + +The server validates tokens against each provider in order until one succeeds. + +### Anonymous authentication + +For development and testing, you can disable authentication entirely: + +```yaml title="registry-anonymous.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPRegistry +metadata: + name: registry +spec: + authConfig: + mode: anonymous + registries: + - name: toolhive + format: toolhive + git: + repository: https://github.com/stacklok/toolhive-catalog.git + branch: main + path: pkg/catalog/toolhive/data/registry.json +``` + +:::danger[No access control] + +Anonymous mode provides **no access control**. Only use it in trusted +environments or when other security measures are in place. **Do not use +anonymous mode in production.** + +::: + +For detailed information about authentication configuration, including +provider-specific examples for Keycloak, Auth0, Azure AD, and Okta, see the +[Authentication configuration](./authentication.mdx) guide. + +## Customize the Registry server pod + +You can customize the Registry server pod using the `podTemplateSpec` field. +This gives you full control over the pod specification. + +```yaml {6-15} title="registry-custom-pod.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPRegistry +metadata: + name: custom-registry +spec: + podTemplateSpec: + spec: + containers: + - name: registry-api # This name must be "registry-api" + resources: + limits: + cpu: '500m' + memory: '512Mi' + requests: + cpu: '100m' + memory: '128Mi' + auth: + mode: anonymous + registries: + - name: toolhive + format: toolhive + git: + repository: https://github.com/stacklok/toolhive-catalog.git + branch: main + path: pkg/catalog/toolhive/data/registry.json + syncPolicy: + interval: '30m' +``` + +:::info[Container name requirement] + +When customizing containers in `podTemplateSpec`, you must use +`name: registry-api` for the main container to ensure the operator can properly +manage the Registry server. The container name is hardcoded to avoid conflict +issues with user provided containers. Mandating a container name on the Operator +side explicitly tells the Operator it is the main registry server container and +any other containers provided by the use are sidecars/init containers. + +::: + +## Check registry status + +To check the status of your registries in a specific namespace: + +```bash +kubectl -n
+ describe mcpregistry
+
+# Check operator logs
+kubectl -n toolhive-system logs -l app.kubernetes.io/name=toolhive-operator
+
+# Verify the operator is running
+kubectl -n toolhive-system get pods -l app.kubernetes.io/name=toolhive-operator
+```
+
+Common causes include:
+
+- **Operator not running**: Ensure the ToolHive operator is deployed and running
+- **RBAC issues**: Check for cluster-level permission issues
+- **Resource quotas**: Check if namespace resource quotas prevent pod creation
+
+
+
+MCPRegistry resource not creating pods
+ +If your `MCPRegistry` resource is created but no pods appear: + +1. Ensure you created the `MCPRegistry` resource in an allowed namespace +1. Check the operator's configuration: + +```bash +helm get values toolhive-operator -n toolhive-system +``` + +1. Check the MCPRegistry status and operator logs: + +```bash +# Check MCPRegistry status +kubectl -n
+ describe mcpregistry
+
+# Check registry pod logs
+kubectl -n logs -l app.kubernetes.io/instance=
+```
+
+Common causes include:
+
+- **Git repository inaccessible**: Verify the repository URL is correct and
+ accessible
+- **ConfigMap/PVC doesn't exist**: Ensure referenced resources exist in the same
+ namespace
+- **Network policies**: Check if network policies are blocking external access
+- **Invalid registry file format**: Verify the registry JSON file is valid
+
+
+
+Registry stuck in Pending or Syncing phase
+ +If the registry is stuck in `Pending` or `Syncing` phase: + +```bash +# Check registry status +kubectl -n
+ logs -l app.kubernetes.io/instance=
+```
+
+Common causes include:
+
+- **Database not reachable**: Verify database host and port are correct
+- **Invalid credentials**: Check that pgpass file is properly mounted
+- **SSL configuration mismatch**: Verify `sslMode` matches your database
+ configuration
+- **Permission issues**: Ensure database users have required privileges
+
+
+
+Database connection errors
+ +If you see database connection errors: + +```bash +# Check registry pod logs +kubectl -n
+ get mcpregistry -o jsonpath='{.status.syncStatus}'
+
+# Trigger manual sync to see immediate errors
+kubectl annotate mcpregistry \
+ toolhive.stacklok.dev/sync-trigger="$(date +%s)" \
+ --overwrite
+
+# Check logs
+kubectl -n logs -l app.kubernetes.io/instance=
+```
+
+Common causes include:
+
+- **Source unavailable**: Git repository, API endpoint, or file is inaccessible
+- **Invalid JSON format**: Registry file contains invalid JSON
+- **Format mismatch**: The `format` field doesn't match the actual data format
+- **Filter too restrictive**: Filters may be excluding all servers
+
+
diff --git a/versioned_docs/version-1.0/toolhive/guides-registry/deployment.mdx b/versioned_docs/version-1.0/toolhive/guides-registry/deployment.mdx
new file mode 100644
index 00000000..8a93e939
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-registry/deployment.mdx
@@ -0,0 +1,34 @@
+---
+title: Deploy the Registry Server
+description: Deployment options for the ToolHive Registry Server in Kubernetes
+---
+
+The Registry server can be deployed in Kubernetes using three methods. Choose
+the one that fits your environment:
+
+| Method | Description |
+| ------------------------------------------------ | --------------------------------------------------------------- |
+| [ToolHive Operator](#toolhive-operator) | Manage the Registry Server lifecycle through `MCPRegistry` CRDs |
+| [Helm](#helm) | Deploy using the Registry Server Helm chart |
+| [Manual manifests](#manual-kubernetes-manifests) | Deploy directly using raw Kubernetes manifests |
+
+## ToolHive Operator
+
+Deploy and manage the Registry server using `MCPRegistry` custom resources. The
+ToolHive Operator watches for these resources and creates the necessary
+infrastructure automatically.
+
+See [Deploy with the ToolHive Operator](./deploy-operator.mdx) for a complete
+guide.
+
+## Helm
+
+A Helm chart is available for the Registry Server. Documentation for this
+deployment method is coming soon.
+
+## Manual Kubernetes manifests
+
+Deploy the Registry Server directly using raw Kubernetes manifests. This
+approach gives you full control over the deployment configuration.
+
+See [Deploy manually](./deploy-manual.mdx) for instructions.
diff --git a/versioned_docs/version-1.0/toolhive/guides-registry/index.mdx b/versioned_docs/version-1.0/toolhive/guides-registry/index.mdx
new file mode 100644
index 00000000..cd771ac8
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-registry/index.mdx
@@ -0,0 +1,20 @@
+---
+title: ToolHive Registry Server
+description:
+ How-to guides for using the ToolHive Registry Server to discover and access
+ MCP servers and skills.
+---
+
+import DocCardList from '@theme/DocCardList';
+
+## Introduction
+
+The ToolHive Registry Server is an implementation of the official
+[Model Context Protocol (MCP) Registry API specification](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/api/generic-registry-api.md).
+It provides a standardized REST API for discovering and accessing MCP servers
+from multiple backend sources, including Kubernetes clusters, Git repositories,
+API endpoints, and local files.
+
+## Contents
+
+Sync failures
+ +If synchronization is failing: + +```bash +# Check sync status +kubectl -n
+
+
+CLI not found in terminal
+ +If `thv` is not recognized after installing ToolHive UI: + +1. **Open a new terminal window**: The PATH changes only take effect in new + terminal sessions. + +1. **Check the Settings > CLI page**: Verify that the PATH Configuration shows + "Valid" status. + +1. **Manually source your shell configuration**: + + ```bash + # Bash + source ~/.bashrc + + # Zsh + source ~/.zshrc + + # Fish + source ~/.config/fish/config.fish + ``` + +1. **Reinstall the CLI**: Go to Settings > CLI and click **Reinstall**. + +
+
+
+Broken symlink after moving ToolHive UI
+ +If you move the ToolHive UI application to a different location, the CLI symlink +may break. To fix this: + +1. Open ToolHive UI from its new location. +1. Go to Settings > CLI. +1. Click **Reinstall** to create a new symlink pointing to the correct location. + +
+
+
+## Related information
+
+- [CLI guides](../guides-cli/index.mdx)
+- [CLI command reference](../reference/cli/thv.md)
+- [CLI conflict resolution](../guides-cli/install.mdx#cli-conflict-resolution)
diff --git a/versioned_docs/version-1.0/toolhive/guides-ui/client-configuration.mdx b/versioned_docs/version-1.0/toolhive/guides-ui/client-configuration.mdx
new file mode 100644
index 00000000..c0d539b9
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-ui/client-configuration.mdx
@@ -0,0 +1,85 @@
+---
+title: Client configuration
+description: How to connect ToolHive to AI clients using the UI.
+---
+
+import ClientIntro from '../_partials/_client-config-intro.mdx';
+
+CLI conflict error when running thv
+ +If you see "CLI conflict detected", you have both ToolHive UI and a standalone +CLI installed. See +[CLI conflict resolution](../guides-cli/install.mdx#cli-conflict-resolution) for +the error message and resolution steps. + ++ +We strive to make ToolHive intuitive and easy to use. If we've missed the mark +on something, [let us know](https://discord.gg/stacklok)! + +:::tip[Advanced users] + +ToolHive UI includes and manages the CLI automatically for terminal access and +advanced features. See [Access the CLI from ToolHive UI](./cli-access.mdx) for +details. + +::: + +## Contents + +
+
+
+Connection Refused error on startup
+ +If you see a "Connection Refused" error when starting ToolHive, your container +runtime (Docker, Podman, or Colima) is likely not installed, not running, or not +configured correctly. + +Follow the instructions in the error message to install or start your container +runtime. For example, if you're using Docker Desktop, make sure it's running and +that the Docker daemon is active. + +If the retry button doesn't work, restart ToolHive. + +
+
+
+### Other issues
+
+For other installation issues, check the
+[GitHub issues page](https://github.com/stacklok/toolhive-studio/issues) or join
+the [Discord community](https://discord.gg/stacklok).
diff --git a/versioned_docs/version-1.0/toolhive/guides-ui/mcp-optimizer.mdx b/versioned_docs/version-1.0/toolhive/guides-ui/mcp-optimizer.mdx
new file mode 100644
index 00000000..e62e03c1
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-ui/mcp-optimizer.mdx
@@ -0,0 +1,120 @@
+---
+title: Optimize MCP tool usage
+description: Enable the MCP Optimizer to enhance tool selection and reduce token usage.
+---
+
+## Overview
+
+The ToolHive MCP Optimizer acts as an intelligent intermediary between AI
+clients and MCP servers. It provides tool discovery, unified access to multiple
+MCP servers through a single endpoint, and intelligent routing of requests to
+appropriate MCP tools.
+
+:::info[Status]
+
+The MCP Optimizer is currently experimental. If you try it out, please share
+your feedback on the [Stacklok Discord community](https://discord.gg/stacklok).
+
+:::
+
+Learn more about the MCP Optimizer, its benefits, and how it works in the
+tutorial:
+[Reduce token usage with MCP Optimizer](../tutorials/mcp-optimizer.mdx).
+
+## Enable MCP Optimizer
+
+:::note[Limitations]
+
+MCP Optimizer does not currently work on Linux hosts or with Podman Desktop on
+Windows. Supported configurations:
+
+- macOS with Docker Desktop, Podman Desktop, or Rancher Desktop
+- Windows with Docker Desktop or Rancher Desktop
+
+MCP Optimizer also does not currently work with MCP servers that have network
+isolation enabled.
+
+:::
+
+To enable the MCP Optimizer in the ToolHive UI:
+
+1. Open the **Settings** (⚙️) screen and enable **MCP Optimizer** under
+ **Experimental Features**
+2. Click the **Configure** button on the notification that pops up, or go to the
+ main **MCP Servers** screen and click **MCP Optimizer** in the left sidebar
+3. Select the group that contains the MCP servers you want to optimize and click
+ **Apply Changes**
+
+ToolHive automatically updates clients that were registered with the selected
+group to use the MCP Optimizer. If you want to connect a new client, go to the
+group which is enabled for optimization and use the **Manage Clients** button to
+register it.
+
+For best results, connect your client to only the optimized group. If you
+connect it to multiple groups, ensure there is no overlap in MCP servers between
+the groups to avoid unpredictable behavior.
+
+:::info[What's happening?]
+
+When you enable MCP Optimizer, ToolHive automatically creates an internal group
+and runs the `mcp-optimizer` MCP server in that group.
+
+The MCP Optimizer server discovers the MCP servers in the selected group and
+builds an index of their tools for intelligent routing. Automatic polling keeps
+the index up to date as servers are added or removed from the optimized group.
+
+ToolHive also disconnects your AI clients from the original MCP server group and
+reconnects them to the MCP Optimizer group.
+
+:::
+
+## Customize MCP Optimizer settings
+
+To update the MCP Optimizer's default settings, click the **Advanced** menu and
+select **Customize MCP Optimizer configuration**. This opens a form where you
+can modify the `mcp-optimizer` MCP server's configuration.
+
+:::note
+
+Changes to the MCP Optimizer configuration might cause the feature to stop
+working correctly. Only modify these settings if you understand their
+implications.
+
+Generally, you should only need to change the Docker image tag and the
+environment variables detailed below.
+
+:::
+
+You can customize the MCP Optimizer's behavior using the following environment
+variables:
+
+- `MAX_TOOLS_TO_RETURN`: Number of tools to return from `find_tool` (default:
+ `8`)
+- `TOOL_DISTANCE_THRESHOLD`: Distance threshold for tool similarity (default:
+ `1.0`)
+- `MAX_TOOL_RESPONSE_TOKENS`: Maximum number of tokens to return from
+ `call_tool` (default: `None`)
+- `WORKLOAD_POLLING_INTERVAL`: Polling interval for running MCP servers, in
+ seconds (default: `60`)
+- `REGISTRY_POLLING_INTERVAL`: Polling interval for ToolHive registry, in
+ seconds (default: `86400`, 24 hours)
+
+## Disable MCP Optimizer
+
+To disable the MCP Optimizer, open the **Settings** (⚙️) screen and disable the
+**MCP Optimizer** option under the **Experimental Features** section.
+
+ToolHive stops and removes the MCP Optimizer server and reconnects your clients
+to the original MCP server group.
+
+## Troubleshooting
+
+If you encounter issues while using the MCP Optimizer, check the logs for
+debugging information. On the **MCP Optimizer** page, click the **Advanced**
+menu and select **MCP Optimizer logs**.
+
+## Related information
+
+- Tutorial:
+ [Reduce token usage with MCP Optimizer](../tutorials/mcp-optimizer.mdx)
+- [Organize MCP servers into groups](./group-management.mdx)
diff --git a/versioned_docs/version-1.0/toolhive/guides-ui/network-isolation.mdx b/versioned_docs/version-1.0/toolhive/guides-ui/network-isolation.mdx
new file mode 100644
index 00000000..89c53566
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-ui/network-isolation.mdx
@@ -0,0 +1,101 @@
+---
+title: Network isolation
+description: How to configure network isolation for MCP servers in ToolHive.
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import ThemedImage from '@theme/ThemedImage';
+
+Most MCP servers require network access to function properly—for example, to
+access APIs, download data, or communicate with other services. However,
+malicious or misconfigured servers can also exfiltrate sensitive data or
+download unwanted content.
+
+When you install an MCP server in ToolHive, you can optionally enable _network
+isolation_. This feature restricts the MCP server's network access to only the
+resources you specify.
+
+:::note
+
+Network isolation currently supports HTTP and HTTPS connections only. Other
+protocols are not supported.
+
+:::
+
+## Enabling network isolation
+
+Network isolation is available for local MCP servers installed from the registry
+or custom servers. It is not available for remote MCP servers, which are hosted
+and outside of ToolHive.
+
+During the MCP server installation, select the **Network isolation** tab in the
+configuration form. Click the toggle to enable it.
+
+When you enable network isolation, any safe default configuration defined in the
+registry is pre-loaded in the form. You can accept these defaults or customize
+the settings to specify which hosts and ports the MCP server is allowed to
+access:
+
+- **Allowed hosts**:\
+ A list of hostnames or IP addresses that the MCP server is allowed to access.
+ This can include APIs, data sources, or other services that the MCP server
+ needs to function properly.
+
+ :::tip
+
+ To allow access to all subdomains under a specific domain, add a leading
+ period (`.`) in front of the hostname. For example, to allow access to all
+ subdomains of `github.com`, enter `.github.com` in the allowed hosts list.
+
+ :::
+
+- **Allowed ports**:\
+ A list of ports that the MCP server is allowed to use for outgoing
+ connections. This can help prevent the MCP server from accessing unauthorized
+ services or resources. For example, port 443 is the default port for HTTPS
+ connections.
+
+:::info[Important]
+
+If you do not specify any allowed hosts or ports, the MCP server will not be
+able to access any external resources, including the internet. This can be
+useful for MCP servers that do not require network access or for testing
+purposes.
+
+:::
+
+## Example configuration
+
+The configuration pictured below allows the MCP server to access
+`api.github.com` and all subdomains of `githubusercontent.com` on port 443
+(HTTPS):
+
+No system tray icon on Linux
+ +Recent versions of Fedora Linux and other distributions have removed the +AppIndicator extension from their default installations. ToolHive requires this +extension for the system tray icon to work properly. + +On Fedora, install the `gnome-shell-extension-appindicator` package: + +```bash +sudo dnf install gnome-shell-extension-appindicator +``` + +You'll need to log out and log back in to activate the extension. + +Alternatively, install the +[Extension Manager](https://github.com/mjakeman/extension-manager) app. It's +available as a native package in many distributions, or you can install it from +[Flathub](https://flathub.org/apps/com.mattjakeman.ExtensionManager). Then, use +Extension Manager to install the +[AppIndicator](https://extensions.gnome.org/extension/615/appindicator-support/) +extension (listed as "AppIndicator and KStatusNotifierItem Support"). + +The ToolHive icon should now appear in your system tray. + ++ +### Accessing other workloads on the same container network + +To allow an MCP server to access other workloads on the same network, you need +to configure network isolation to include the appropriate hostnames and ports. +This is commonly needed when your MCP server needs to communicate with +databases, APIs, or other services that are running on your local host during +development. + +For example, in Docker environments, you can add `host.docker.internal` to +access services on the host. `host.docker.internal` is a special hostname +provided by Docker that resolves to the host machine's IP address from within +containers. + +- **Allowed hosts**: `host.docker.internal` +- **Allowed ports**: `3000` + +## Related information + +- [Run MCP servers](./run-mcp-servers.mdx) diff --git a/versioned_docs/version-1.0/toolhive/guides-ui/playground.mdx b/versioned_docs/version-1.0/toolhive/guides-ui/playground.mdx new file mode 100644 index 00000000..fe681cce --- /dev/null +++ b/versioned_docs/version-1.0/toolhive/guides-ui/playground.mdx @@ -0,0 +1,266 @@ +--- +title: Test MCP servers +description: + Use the playground feature to test and validate MCP servers directly in the + ToolHive UI with AI model providers. +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; +import ThemedImage from '@theme/ThemedImage'; + +ToolHive's playground lets you test and validate MCP servers directly in the UI +without requiring additional client setup. This streamlined testing environment +helps you quickly evaluate functionality and behavior before deploying MCP +servers to production environments. + +## Key capabilities + +### Instant testing of MCP servers + +Configure your AI model providers, select your MCP servers and tools, and begin +testing immediately in the desktop app. The playground eliminates the friction +of setting up external AI clients just to validate that your MCP servers work +correctly. + +### Detailed interaction logs + +See tool details, parameters, and execution results directly in the UI, ensuring +full visibility into tool performance and responses. Every interaction is +logged, making it easy to understand exactly what your MCP servers are doing and +how they respond to requests. + +### Integrated ToolHive management + +The playground includes a built-in MCP server that lets you manage your other +MCP servers directly through natural language commands. You can list servers, +check their status, start or stop them, and perform other management tasks using +conversational AI. + +## Getting started + +To start using the playground: + +1. **Access the playground**: Click the **Playground** tab in the ToolHive UI + navigation bar. + +2. **Configure provider settings**: Click **Provider Settings** to set up access + to AI model providers: + - **OpenAI**: Enter your OpenAI API key to use GPT models + - **Anthropic**: Add your Anthropic API key for Claude models + - **Google**: Configure Google AI API key for Gemini models + - **xAI**: Set up xAI API key for Grok models + - **Ollama**: Enter the server URL to connect to your local Ollama instance + (default: `http://localhost:11434`) + - **LM Studio**: Enter the server URL from the **Developer** section in LM + Studio where you started the local server (default: + `http://localhost:1234`) + - **OpenRouter**: Add OpenRouter API key for access to multiple model + providers + +3. **Select MCP tools**: Click the tools icon to manage which MCP servers and + tools are available in the playground. + - View all your running MCP servers + - Enable or disable specific tools from each server + - Search and filter tools by name or functionality + - The `toolhive mcp` server is included by default, providing management + capabilities + +
+
+
+Provider not working
+ +If your provider isn't working: + +1. **For API key-based providers** (OpenAI, Anthropic, Google, xAI, OpenRouter): + - Verify the API key is correct and has proper permissions + - Check that you have sufficient quota or credits with the provider + - Ensure the API key hasn't expired or been revoked + - Try creating a new API key from the provider's dashboard + +2. **For local providers** (Ollama, LM Studio): + - Verify the server is running and accessible at the configured URL + - Check that the server URL is correct and includes the port number + - Ensure no firewall or network settings are blocking the connection + - For LM Studio, confirm you started the server in the **Developer** section + +
+
+
+MCP tools not appearing
+ +If your MCP server tools aren't showing up: + +1. Verify the MCP server is running (check the **MCP Servers** page) +2. Click the tools icon and ensure the server's tools are enabled +3. Try restarting the MCP server if it shows as unhealthy +4. Check the server logs for any error messages + +
+
+
+## Next steps
+
+- Learn about [client configuration](./client-configuration.mdx) to connect
+ ToolHive to external AI applications
+- Set up [secrets management](./secrets-management.mdx) for secure handling of
+ API keys and tokens
+- Explore [network isolation](./network-isolation.mdx) for enhanced security
+ when testing untrusted MCP servers
+- Browse the [registry](./registry.mdx) to discover new MCP servers to test in
+ the playground
+
+## Related information
+
+- [Run MCP servers](./run-mcp-servers.mdx)
+- [Install ToolHive](./install.mdx)
diff --git a/versioned_docs/version-1.0/toolhive/guides-ui/quickstart.mdx b/versioned_docs/version-1.0/toolhive/guides-ui/quickstart.mdx
new file mode 100644
index 00000000..89071826
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-ui/quickstart.mdx
@@ -0,0 +1,162 @@
+---
+title: 'Quickstart: ToolHive UI'
+sidebar_label: Quickstart
+description:
+ A step-by-step guide to installing the ToolHive desktop application and
+ running your first MCP server.
+---
+
+In this tutorial, you'll install the ToolHive desktop application and run your
+first MCP server. By the end, you'll have a working MCP server that can fetch
+content from websites and be used by AI applications like GitHub Copilot or
+Cursor.
+
+## What you'll learn
+
+- How to install ToolHive on your system
+- How to find available MCP servers
+- How to run an MCP server
+- How to use the server with an AI client application
+
+## Prerequisites
+
+Before starting this tutorial, make sure you have:
+
+- [Docker](https://docs.docker.com/get-docker/) or
+ [Podman](https://podman-desktop.io/downloads) or
+ [Colima](https://github.com/abiosoft/colima) installed and running
+- A [supported MCP client](../reference/client-compatibility.mdx) like GitHub
+ Copilot in VS Code, Cursor, Claude Code, and more
+
+## Step 1: Install the ToolHive UI
+
+First, download and run the ToolHive installer for your system.
+
+- **macOS**: download the DMG installer for
+ [Apple silicon](https://github.com/stacklok/toolhive-studio/releases/latest/download/ToolHive-arm64.dmg)
+ or
+ [Intel-based](https://github.com/stacklok/toolhive-studio/releases/latest/download/ToolHive-x64.dmg)
+ Macs and copy the ToolHive application to your Applications folder
+- **Windows**: download and run the
+ [installer](https://github.com/stacklok/toolhive-studio/releases/latest/download/ToolHive.Setup.exe)
+
+- **Linux**: download the RPM or DEB package from the
+ [releases page](https://github.com/stacklok/toolhive-studio/releases/latest)
+ and install it using your package manager.
+
+For more detailed installation instructions, see the
+[installing ToolHive](../guides-ui/install.mdx) guide.
+
+## Step 2: Find an MCP server to run
+
+On the initial splash screen, click **Browse registry**, or open the
+**Registry** page from the top menu bar. This page lists the MCP servers in
+ToolHive's built-in registry.
+
+:::info[What is this?]
+
+ToolHive maintains a curated registry of MCP servers that have been verified to
+work correctly. The registry includes information about what each server does
+and how to use it.
+
+:::
+
+For this tutorial, you'll use the "fetch" server, which is a simple MCP server
+that lets AI agents get the contents of a website. Click on the "fetch" server
+to start the installation process.
+
+## Step 3: Install the Fetch MCP server
+
+The Fetch MCP server doesn't require any special configuration, so you can
+install it with the default settings. Click the **Install server** button to
+start the installation.
+
+Once the server is installed, it will appear on the **MCP Servers** page.
+
+:::info[What's happening?]
+
+ToolHive downloads the container image for the fetch server, creates a container
+with the appropriate security settings, and starts the server. It also sets up a
+proxy process that lets your AI agent communicate with the server.
+
+:::
+
+## Step 4: Connect an AI client
+
+On the **Clients** page, you'll see the supported AI clients that ToolHive can
+manage for you. When you connect a client, ToolHive configures it to use the MCP
+servers you have installed.
+
+Click the toggle switch to connect the client you want to use.
+
+:::info[What's happening?]
+
+When you connect a supported client, ToolHive automatically configures it to use
+MCP servers that you install. This means you don't have to manually configure
+the client each time you run an MCP server.
+
+:::
+
+## Step 5: Use the MCP server with your client
+
+Now that your MCP server is running and your client is connected to ToolHive,
+you can use the MCP server's tools. Open your client and ask the AI to fetch
+content from a website. Note that you might need to restart your client for the
+changes to take effect.
+
+For example, try asking: "Can you fetch the content from https://toolhive.dev
+and summarize it for me?"
+
+The AI should be able to use the Fetch MCP server to retrieve the content and
+provide a summary.
+
+:::info[What's happening?]
+
+When you ask the AI agent to fetch content, the large language model (LLM)
+determines that it needs external data. It discovers the fetch tool provided by
+your MCP server, instructs the agent to execute the tool with the URL you
+specified, then receives and processes the webpage content to create a summary.
+
+:::
+
+## What's next?
+
+Congratulations! You've successfully installed ToolHive and run your first MCP
+server. Here are some next steps to explore:
+
+- Learn more about MCP concepts in the
+ [MCP primer guide](../concepts/mcp-primer.mdx)
+- Try [running more MCP servers](../guides-ui/run-mcp-servers.mdx) from the
+ registry or from custom sources
+- Learn about [secrets management](../guides-ui/secrets-management.mdx) for MCP
+ servers that require authentication
+- Learn how to
+ [manually configure clients](../reference/client-compatibility.mdx#manual-configuration)
+ that ToolHive doesn't automatically configure
+
+## Troubleshooting
+
+Tool execution failing
+ +If tools are failing to execute: + +1. Check the tool's parameter requirements in the audit log +2. Verify any required secrets or environment variables are configured +3. Ensure the MCP server has necessary permissions (network access, file system + access) +4. Review the server logs for detailed error information + +
+
+
+Server fails to start
+ +If the server fails to start, check: + +- Is Docker, Podman, or Colima running? +- Do you have internet access to pull the container image? + +
+
+
+If you encounter any problems, please join our
+[Discord community](https://discord.gg/stacklok) for help.
diff --git a/versioned_docs/version-1.0/toolhive/guides-ui/registry.mdx b/versioned_docs/version-1.0/toolhive/guides-ui/registry.mdx
new file mode 100644
index 00000000..f7ac4fcb
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-ui/registry.mdx
@@ -0,0 +1,147 @@
+---
+title: Explore the registry
+description: How to use the built-in or custom registry to find MCP servers.
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import ThemedImage from '@theme/ThemedImage';
+
+ToolHive includes a built-in registry of MCP servers with verified
+configurations that meet a
+[minimum quality standard](../concepts/registry-criteria.mdx), allowing you to
+discover and deploy high-quality tools effortlessly. You can browse the
+registry, select servers, and run them securely through the user interface.
+
+You can also configure ToolHive to use a custom registry instead. This is useful
+for organizations that want to maintain their own private registry of MCP
+servers.
+
+## Find MCP servers
+
+The ToolHive interface includes a dedicated **Registry** section in the main
+menu. This section lets you explore the various MCP servers available in either
+the built-in or custom registry.
+
+Client can't use the server
+ +If your AI client application can't use the server: + +- Make sure your client is connected to ToolHive (see Step 4) +- Restart your client to pick up the new configuration +- Verify the server is running on the **MCP Servers** page +- Disconnect and reconnect the client in ToolHive to refresh the configuration + +
+or remote {/* prettier-ignore */} 
) from the registry:
+
+1. Open the **Registry** page from the menu bar.
+1. Browse or search for the MCP server you want to install.
+1. Click on the desired MCP server to open its details page. Here you can review
+ more information about the server like its:
+ - Description
+ - Available tools
+ - Tier (community or official)
+ - Popularity (GitHub stars)
+ - A link to the GitHub repository for more details and usage documentation
+1. Click the **Install server** button to start the installation process.
+
+### Configure the server
+
+
+ {' '}Local MCP
+
+ }
+ default>
+
+**Local MCP servers** run directly on your machine using your container runtime.
+
+The configuration form is pre-filled with defaults from the registry. Enter the
+remaining required information and adjust any optional settings as needed:
+
+1. **Server name**: A unique name for the MCP server.\
+ This defaults to the MCP server's name in the registry. If you want to run
+ multiple instances of the same MCP server, give each instance a unique name.
+
+1. **Group**: The group where this server will be added. [Optional]\
+ Select an existing group or keep the default. Groups help you organize
+ servers and control client access. See
+ [Organize servers into groups](./group-management.mdx) for details.
+
+1. **Command arguments** (optional):\
+ Enter any command-line arguments needed to run the MCP server. These might be
+ needed to pass application-specific parameters to the MCP server. Refer to
+ the MCP server's documentation for details.
+
+ :::info
+
+ We've made every effort to include sensible defaults in the registry for a
+ one-click experience, but some servers may require additional command-line
+ arguments to function correctly.
+
+ :::
+
+1. **Storage volumes** [Optional]:\
+ Map files or folders from your local host to the MCP server. See
+ [Mount host files and folders](#volumes). [Optional]
+
+1. **Secrets** and **environment variables** expected by the server are
+ populated from the registry automatically. Required values are marked with an
+ asterisk (\*).
+ 1. **Secrets**: Enter a value to create a new secret or select an existing
+ secret to map to the environment variable. Secrets are stored securely and
+ can be used by the MCP server without exposing them in plaintext.
+ 2. **Environment variables**: Enter the value in the input field alongside
+ the variable name. These are typically used for configuration options that
+ do not require sensitive data.
+
+1. **Network isolation** [Optional]:\
+ Enable network isolation to restrict the MCP server's network access. This
+ enhances security by limiting the server's ability to communicate with
+ external networks. See the [Network isolation](./network-isolation.mdx) guide
+ for details.
+
+:::note
+
+Refer to the MCP server's documentation for the required configuration
+information, permissions, and authentication details. A link to the GitHub
+repository is provided on each server's details page.
+
+:::
+
+
+ {' '}Remote MCP
+
+ }>
+
+**Remote MCP servers** are hosted services that you connect to.
+
+The configuration form is pre-filled with defaults from the registry. Enter the
+remaining required information and adjust any optional settings as needed:
+
+1. A unique **name** for the MCP server. [Required]
+1. **Group**: The group where this server will be added. [Optional]\
+ Select an existing group or keep the default. Groups help you organize
+ servers and control client access. See
+ [Organize servers into groups](./group-management.mdx) for details.
+1. The **URL** of the remote MCP server. [Required]
+1. The **transport protocol** that the MCP server uses. [Required]\
+ ToolHive supports server-sent events (SSE) and Streamable HTTP (default) for
+ real-time communication. The protocol must match what the MCP server
+ supports.
+1. **Authorization method**: Choose how ToolHive should authenticate with the
+ remote server.\
+ The default is **Auto-Discovered**. Use this option for MCP servers that
+ fully implement the MCP authorization spec including dynamic client
+ registration (RFC7591) or for servers that do not require authentication.
+ ToolHive automatically:
+ - Discovers OAuth/OIDC endpoints
+ - Registers a new OAuth client
+ - Obtains and manages client credentials
+ - Handles token lifecycle automatically
+
+ For MCP servers that require manual configuration, ToolHive supports OAuth2
+ and OIDC authentication. Obtain the necessary information from the MCP
+ server's documentation or administrator.
+
+ **OAuth2 authentication options:**
+ - **Authorize URL**: The URL where users are redirected to authenticate and
+ authorize access to the MCP server. [Required]
+ - **Token URL**: The URL where your application exchanges the authorization
+ code for access tokens. [Required]
+ - **Client ID**: Your application's identifier registered with the OAuth
+ provider. [Required]
+ - **Client secret**: The secret key that proves your application's identity.
+ Enter a value to create a new secret or select an existing secret from the
+ provider. Secrets are stored securely and can be used by the MCP server
+ without exposing them in plaintext. See
+ [Secrets management](./secrets-management.mdx) for details. [Optional]
+ - **Scopes**: List of permissions your application is requesting. [Optional]
+ - **PKCE**: Enable Proof Key for Code Exchange (RFC 7636) for enhanced
+ security without requiring a client secret. [Optional]
+
+ **OIDC authentication options:**
+ - **Issuer URL**: The base URL of the OIDC provider. [Required]
+ - **Client ID**: Your application's identifier registered with the OIDC
+ provider. [Required]
+ - **Client secret**: The secret key that proves your application's identity.
+ Enter a value to create a new secret or select an existing secret from the
+ provider. Secrets are stored securely and can be used by the MCP server
+ without exposing them in plaintext. See
+ [Secrets management](./secrets-management.mdx) for details. [Optional]
+ - **PKCE**: Enable Proof Key for Code Exchange (RFC 7636) for enhanced
+ security without requiring a client secret. [Optional]
+
+1. The **callback port** for the authentication redirect. [Optional]
+
+1. **Custom headers** [Optional]:\
+ Add custom HTTP headers to inject into requests to the remote MCP server.
+ - **Plaintext headers**: Add static key-value pairs for headers like
+ `X-Tenant-ID` or correlation IDs. These values are stored and transmitted
+ in plaintext.
+ - **Headers from secrets**: For sensitive data like API keys, add headers
+ whose values are retrieved from ToolHive's secrets manager. Enter a header
+ name and either select an existing secret or enter a new value to create
+ one.
+
+Click **Install server** to connect to the remote MCP server.
+
+
+
+
+ View examples of remote MCP authentication configuration
+ +
+ {' '}Custom local MCP
+
+ }
+ default>
+
+On the **MCP Servers** page, click **Add an MCP server**, then choose **Add
+custom local server** in the drop-down menu. Or if this is your first MCP
+server, on the introductory screen.
+
+In the **Custom MCP server** dialog, choose [Docker image](#from-a-docker-image)
+or [Package manager](#from-a-source-package).
+
+{/* prettier-ignore */}
+
+ {' '}Custom remote MCP
+
+ }>
+
+On the **MCP Servers** page, click **Add an MCP server**, then choose **Add a
+remote MCP server** in the drop-down menu.
+
+On the configuration form, enter:
+
+1. A unique **name** for the MCP server. [Required]
+2. **Group**: The group where this server will be added. [Optional]\
+ Select an existing group or keep the default. Groups help you organize
+ servers and control client access. See
+ [Organize servers into groups](./group-management.mdx) for details.
+3. The **URL** of the remote MCP server. [Required]
+4. The **transport protocol** that the MCP server uses. [Required]\
+ ToolHive supports server-sent events (SSE) and Streamable HTTP (default) for
+ real-time communication. The protocol must match what the MCP server
+ supports.
+5. **Authorization method**: Choose how ToolHive should authenticate with the
+ remote server.\
+ The default is **Auto-Discovered**. Use this option for MCP servers that
+ fully implement the MCP authorization spec including dynamic client
+ registration (RFC7591) or for servers that do not require authentication.
+ ToolHive automatically:
+ - Discovers OAuth/OIDC endpoints
+ - Registers a new OAuth client
+ - Obtains and manages client credentials
+ - Handles token lifecycle automatically
+
+ For MCP servers that require manual configuration, ToolHive supports OAuth2
+ and OIDC authentication. Obtain the necessary information from the MCP
+ server's documentation or administrator.
+
+ **OAuth2 authentication options:**
+ - **Authorize URL**: The URL where users are redirected to authenticate and
+ authorize access to the MCP server. [Required]
+ - **Token URL**: The URL where your application exchanges the authorization
+ code for access tokens. [Required]
+ - **Client ID**: Your application's identifier registered with the OAuth
+ provider. [Required]
+ - **Client secret**: The secret key that proves your application's identity.
+ Enter a value to create a new secret or select an existing secret from the
+ provider. Secrets are stored securely and can be used by the MCP server
+ without exposing them in plaintext. See
+ [Secrets management](./secrets-management.mdx) for details. [Optional]
+ - **Scopes**: List of permissions your application is requesting. [Optional]
+
+ **OIDC authentication options:**
+ - **Issuer URL**: The base URL of the OIDC provider. [Required]
+ - **Client ID**: Your application's identifier registered with the OIDC
+ provider. [Required]
+ - **Client secret**: The secret key that proves your application's identity.
+ Enter a value to create a new secret or select an existing secret from the
+ provider. Secrets are stored securely and can be used by the MCP server
+ without exposing them in plaintext. See
+ [Secrets management](./secrets-management.mdx) for details. [Optional]
+ - **PKCE**: Enable Proof Key for Code Exchange (RFC 7636) for enhanced
+ security without requiring a client secret. [Optional]
+
+6. The **callback port** for the authentication redirect. [Optional]
+
+7. **Custom headers** [Optional]:\
+ Add custom HTTP headers to inject into requests to the remote MCP server.
+ - **Plaintext headers**: Add static key-value pairs for headers like
+ `X-Tenant-ID` or correlation IDs. These values are stored and transmitted
+ in plaintext.
+ - **Headers from secrets**: For sensitive data like API keys, add headers
+ whose values are retrieved from ToolHive's secrets manager. Enter a header
+ name and either select an existing secret or enter a new value to create
+ one.
+
+Click **Install server** to connect to the remote MCP server.
+
+
+
+
+ View examples of remote MCP authentication configuration
+ +Client → vMCP"] + end + + subgraph vMCP["Virtual MCP Server (vMCP)"] + Auth[Token validation] + Backend[Backend auth] + end + + subgraph Boundary2[" "] + direction TB + B2Label["**Boundary 2**
vMCP → Backend APIs"] + GitHub[GitHub API] + Jira[Jira API] + end + + Client -->|"vMCP-scoped
token"| Auth + Auth --> Backend + Backend -->|"Backend-scoped
token"| GitHub + Backend -->|"Backend-scoped
token"| Jira +``` + +**Boundary 1 (Incoming):** Clients authenticate to vMCP using OAuth 2.1 +authorization as defined in the +[MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization). +This is your organization's identity layer. + +**Boundary 2 (Outgoing):** vMCP obtains appropriate credentials for each +backend. Each backend API receives a token or credential scoped to its +requirements. + +## Incoming authentication + +Configure how clients authenticate to vMCP. + +### Anonymous (development only) + +No authentication required: + +```yaml title="VirtualMCPServer resource" +spec: + incomingAuth: + type: anonymous +``` + +:::warning + +Do not use `anonymous` authentication in production environments. This setting +disables all access control, allowing anyone to use the vMCP without +credentials. + +::: + +### OIDC authentication + +Validate tokens from an external identity provider: + +```yaml title="VirtualMCPServer resource" +spec: + incomingAuth: + type: oidc + oidcConfig: + type: inline + inline: + issuer: https://auth.example.com + clientId:
+
+
+Backends not appearing in status
+ +**Symptoms:** + +- `status.discoveredBackends` is empty or missing backends +- `status.backendCount` is 0 or lower than expected + +**Possible causes and solutions:** + +1. **MCPGroup not in Ready state** + + ```bash + kubectl get mcpgroup my-group -n toolhive-system + ``` + + Wait for the group to reach Ready state before starting vMCP. + +2. **Backend resources not referencing the correct group** + + ```bash + kubectl get mcpserver,mcpremoteproxy -n toolhive-system \ + -o custom-columns=NAME:.metadata.name,GROUP:.spec.groupRef + ``` + + Ensure all backends have `spec.groupRef` matching the VirtualMCPServer's + `spec.config.groupRef`. + +3. **vMCP pod not restarted after backend changes** + + Backend changes require a pod restart to be discovered: + + ```bash + kubectl rollout restart deployment vmcp-my-vmcp -n toolhive-system + ``` + +4. **RBAC permissions missing (discovered mode)** + + Check the vMCP service account has required permissions: + + ```bash + kubectl get role -n toolhive-system | grep vmcp + kubectl describe role vmcp-my-vmcp -n toolhive-system + ``` + + The operator should create these automatically. If missing, delete and + recreate the VirtualMCPServer resource. + +
+
+
+Backends showing as unavailable
+ +**Symptoms:** + +- `status.discoveredBackends[].status` is `unavailable` or `unknown` +- `/status` endpoint shows `health: unhealthy` + +**Possible causes and solutions:** + +1. **Backend pod not running** + + ```bash + kubectl get pods -n toolhive-system -l app.kubernetes.io/name=my-backend + ``` + + Check backend pod logs for errors: + + ```bash + kubectl logs -n toolhive-system deployment/my-backend + ``` + +2. **Backend service not accessible** + + Test connectivity from vMCP pod: + + ```bash + kubectl exec -n toolhive-system deployment/vmcp-my-vmcp -- \ + wget -O- http://my-backend:8080/health + ``` + +3. **Authentication failing** + + Check vMCP logs for auth errors: + + ```bash + kubectl logs -n toolhive-system deployment/vmcp-my-vmcp | grep ERROR + ``` + + Common auth issues: + - Invalid OIDC configuration in MCPExternalAuthConfig + - Expired or invalid client secrets + - Token exchange endpoint unreachable + +4. **Backend returning errors on initialize** + + The backend may be misconfigured or failing to start properly. Check backend + logs and ensure it responds correctly to MCP `initialize` requests. + +
+
+
+RBAC permission errors
+ +**Symptoms:** + +- vMCP logs show `forbidden` or `unauthorized` errors +- Backends not being discovered in discovered mode + +**Error examples:** + +```text +Failed to list MCPServers: mcpservers.toolhive.stacklok.dev is forbidden: +User "system:serviceaccount:toolhive-system:vmcp-my-vmcp" cannot list +resource "mcpservers" +``` + +**Solutions:** + +1. **Verify service account and role binding exist** + + ```bash + kubectl get serviceaccount vmcp-my-vmcp -n toolhive-system + kubectl get role vmcp-my-vmcp -n toolhive-system + kubectl get rolebinding vmcp-my-vmcp -n toolhive-system + ``` + +2. **Check role permissions** + + ```bash + kubectl describe role vmcp-my-vmcp -n toolhive-system + ``` + + Required permissions for discovered mode: + - `configmaps`, `secrets`: get, list, watch + - `mcpgroups`, `mcpservers`, `mcpremoteproxies`: get, list, watch + - `mcpexternalauthconfigs`, `mcptoolconfigs`: get, list, watch + - `virtualmcpservers/status`: update, patch + +3. **Recreate RBAC resources** + + If RBAC resources are missing or incorrect, delete and recreate the + VirtualMCPServer: + + ```bash + kubectl delete virtualmcpserver my-vmcp -n toolhive-system + kubectl apply -f my-vmcp.yaml + ``` + + The operator will recreate all RBAC resources automatically. + +
+
+
+Mode switching issues
+ +**Symptoms:** + +- vMCP pod fails to start after switching modes +- Configuration validation errors + +**Switching from discovered to inline:** + +Ensure you define `spec.config.backends[]` before changing `source` to `inline`: + +```yaml +spec: + config: + backends: [] # ❌ Empty array will fail validation +``` + +**Switching from inline to discovered:** + +Remove the `spec.config.backends[]` array when switching to discovered mode: + +```yaml +spec: + config: + backends: [...] # ❌ Should be removed in discovered mode +``` + +
+
+
+Health check failures
+ +**Symptoms:** + +- `/status` endpoint shows backends as `degraded` or `unhealthy` +- Intermittent backend availability + +**Possible causes:** + +1. **Backend service overloaded or slow** + + Health checks timeout after 10 seconds (default `healthCheckTimeout`). If + backends are slow to respond, they'll be marked unhealthy even if functional. + +2. **Network issues between vMCP and backends** + + Check network policies and service mesh configuration that might block or + slow connections. + +3. **Backend requires authentication for initialize** + + Ensure `externalAuthConfigRef` is properly configured if the backend requires + authentication. + +
+
+
+## Related information
+
+- [Configure vMCP servers](./configuration.mdx)
+- [Authentication](./authentication.mdx)
+- [VirtualMCPServer CRD specification](../reference/crd-spec.md#apiv1alpha1virtualmcpserver)
diff --git a/versioned_docs/version-1.0/toolhive/guides-vmcp/composite-tools.mdx b/versioned_docs/version-1.0/toolhive/guides-vmcp/composite-tools.mdx
new file mode 100644
index 00000000..6656d962
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-vmcp/composite-tools.mdx
@@ -0,0 +1,637 @@
+---
+title: Composite tools and workflows
+description: Create multi-step workflows that span multiple backend MCP servers.
+---
+
+Composite tools let you define multi-step workflows that execute across multiple
+backend MCP servers with parallel execution, conditional logic, approval gates,
+and error handling.
+
+## Overview
+
+A composite tool combines multiple backend tool calls into a single workflow.
+When a client calls a composite tool, vMCP orchestrates the execution across
+backend MCP servers, handling dependencies and collecting results.
+
+## Key capabilities
+
+- **Parallel execution**: Independent steps run concurrently; dependent steps
+ wait for their prerequisites
+- **Template expansion**: Dynamic arguments using step outputs
+- **Elicitation**: Request user input mid-workflow (approval gates, choices)
+- **Error handling**: Configurable abort, continue, or retry behavior
+- **Timeouts**: Workflow and per-step timeout configuration
+
+:::info
+
+Elicitation (user prompts during workflow execution) is defined in the CRD but
+has not been extensively tested. Test thoroughly in non-production environments
+first.
+
+:::
+
+## Configuration location
+
+Composite tools are defined in the VirtualMCPServer resource under
+`spec.config.compositeTools`:
+
+```yaml
+apiVersion: toolhive.stacklok.dev/v1alpha1
+kind: VirtualMCPServer
+metadata:
+ name: my-vmcp
+spec:
+ incomingAuth:
+ type: anonymous
+ config:
+ groupRef: my-tools
+ # ... other configuration ...
+ compositeTools:
+ - name: my_workflow
+ description: A multi-step workflow
+ parameters:
+ # Input parameters (JSON Schema)
+ steps:
+ # Workflow steps
+```
+
+For complex, reusable workflows, you can also reference external
+`VirtualMCPCompositeToolDefinition` resources using
+`spec.config.compositeToolRefs`.
+
+## Simple example
+
+Here's a composite tool that searches arXiv for papers on a topic and reads the
+top result. This example assumes you have an MCPServer resource named `arxiv` in
+a group that your vMCP server references, and that you're using the default
+[conflict resolution strategy](./tool-aggregation.mdx#conflict-resolution-strategies)
+and prefix format (`Configuration validation errors
+ +**Missing groupRef:** + +```text +Error: spec.config.groupRef is required +``` + +**Fix:** Add `spec.config.groupRef` referencing an existing MCPGroup. + +**Invalid backend URL in inline mode:** + +```text +Error: spec.config.backends[0].url must start with http:// or https:// +``` + +**Fix:** Ensure backend URLs use proper scheme: + +```yaml +backends: + - name: my-backend + url: http://my-backend.default.svc.cluster.local:8080 # Valid + # url: my-backend:8080 # Invalid +``` + +**Missing backends array in inline mode:** + +```text +Error: spec.config.backends is required when outgoingAuth.source is "inline" +``` + +**Fix:** Define at least one backend in `spec.config.backends` when using inline +mode. + +**Invalid transport protocol:** + +```text +Error: spec.config.backends[0].transport must be "sse" or "streamable-http" +``` + +**Fix:** Use only supported transport protocols: + +```yaml +backends: + - name: my-backend + transport: sse # Valid + # transport: stdio # Invalid for inline backends +``` + +**Referenced MCPExternalAuthConfig not found:** + +```text +Error: MCPExternalAuthConfig "github-token-config" not found in namespace "toolhive-system" +``` + +**Fix:** Create the MCPExternalAuthConfig resource before referencing it, or +remove the auth reference. + +
+
+
+Circuit breaker opens too frequently
+ +If the circuit breaker is too sensitive: + +**Increase failure threshold:** + +```yaml +operational: + failureHandling: + circuitBreaker: + failureThreshold: 10 # Require more failures before opening +``` + +**Increase timeout:** + +```yaml +operational: + failureHandling: + circuitBreaker: + timeout: 120s # Give backends more time to recover +``` + +
+
+
+Backends not recovering automatically
+ +If backends stay unhealthy after recovering: + +1. **Test backend connectivity** + + Verify the backend MCP server is accessible from vMCP: + + ```bash + kubectl exec -n toolhive-system deployment/vmcp-my-vmcp -- \ + curl -v http://my-backend:8080/mcp + ``` + + The backend should respond with MCP protocol headers. + +2. **Increase circuit breaker timeout** + + ```yaml + operational: + failureHandling: + circuitBreaker: + timeout: 90s # Allow more time for full recovery + ``` + +3. **Review vMCP logs** + + ```bash + kubectl logs -n toolhive-system deployment/vmcp-my-vmcp + ``` + + Look for circuit breaker state transitions: + + ``` + WARN Circuit breaker for backend github-mcp OPENED (threshold exceeded) + INFO Circuit breaker for backend github-mcp CLOSED (recovery successful) + ``` + +
+
+
+## Related information
+
+- [Backend discovery modes](./backend-discovery.mdx) - Backend health status and
+ `/status` endpoint
+- [Configuration guide](./configuration.mdx)
+- [VirtualMCPServer CRD specification](../reference/crd-spec.md#apiv1alpha1virtualmcpserver)
diff --git a/versioned_docs/version-1.0/toolhive/guides-vmcp/index.mdx b/versioned_docs/version-1.0/toolhive/guides-vmcp/index.mdx
new file mode 100644
index 00000000..b6f898e7
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-vmcp/index.mdx
@@ -0,0 +1,26 @@
+---
+title: Virtual MCP Server
+description: Aggregate multiple MCP servers into a single unified endpoint.
+---
+
+Virtual MCP Server (vMCP) is a feature of the ToolHive Kubernetes Operator that
+aggregates multiple backend MCP servers into a single endpoint, enabling unified
+tool access, centralized authentication, and multi-step workflows.
+
+## When to use vMCP
+
+- You manage multiple MCP servers that should appear as one
+- You need to centralize authentication across backends
+- You want to create reusable workflows spanning multiple systems
+
+## Get started
+
+- [Understanding Virtual MCP Server](../concepts/vmcp.mdx) - Learn what vMCP
+ does and when to use it
+- [Quickstart: Virtual MCP Server](./quickstart.mdx) - Deploy your first vMCP
+
+## Contents
+
+import DocCardList from '@theme/DocCardList';
+
+Healthy backends marked unhealthy
+ +If backends are incorrectly marked unhealthy: + +**Increase health check timeout:** + +```yaml +operational: + failureHandling: + healthCheckTimeout: 20s # Allow slower responses +``` + +**Increase unhealthy threshold:** + +```yaml +operational: + failureHandling: + unhealthyThreshold: 5 # Allow more failures before marking unhealthy +``` + +
+
+
+VirtualMCPServer stuck in Pending
+ +Check that the MCPGroup exists and backend MCPServers are running: + +```bash +kubectl get mcpgroups,mcpservers -n toolhive-system +``` + +Check the operator logs: + +```bash +kubectl logs -n toolhive-system -l app.kubernetes.io/name=toolhive-operator +``` + +
+
diff --git a/versioned_docs/version-1.0/toolhive/guides-vmcp/scaling-and-performance.mdx b/versioned_docs/version-1.0/toolhive/guides-vmcp/scaling-and-performance.mdx
new file mode 100644
index 00000000..559dec02
--- /dev/null
+++ b/versioned_docs/version-1.0/toolhive/guides-vmcp/scaling-and-performance.mdx
@@ -0,0 +1,88 @@
+---
+title: Scaling and Performance
+description: How to scale Virtual MCP Server deployments vertically and horizontally.
+---
+
+This guide explains how to scale Virtual MCP Server (vMCP) deployments.
+
+## Vertical scaling
+
+Vertical scaling (increasing CPU/memory per instance) is the simplest approach
+and works for all use cases, including stateful backends.
+
+To increase resources, configure `podTemplateSpec` in your VirtualMCPServer:
+
+```yaml
+spec:
+ podTemplateSpec:
+ spec:
+ containers:
+ - name: vmcp
+ resources:
+ requests:
+ cpu: '500m'
+ memory: 512Mi
+ limits:
+ cpu: '1'
+ memory: 1Gi
+```
+
+Vertical scaling is recommended as the starting point for most deployments.
+
+## Horizontal scaling
+
+Horizontal scaling (adding more replicas) can improve availability and handle
+higher request volumes.
+
+### How to scale horizontally
+
+The VirtualMCPServer CRD does not have a `replicas` field. The operator creates
+a Deployment named `vmcp-Only some tools appearing
+ +Verify both backends are discovered: + +```bash +kubectl get virtualmcpserver demo-vmcp -n toolhive-system -o jsonpath='{.status.discoveredBackends[*].name}' +``` + +Check backend health in the status: + +```bash +kubectl describe virtualmcpserver demo-vmcp -n toolhive-system +``` + ++ +--- + +
+
+
+## ToolHive components
+
+ToolHive includes everything you need to use MCP servers in production. It's
+made up of four key components: the Runtime, Registry Server, Gateway, and
+Portal.
+
+
+
+### Desktop app
+
+Run MCP servers with one click. The easiest way to get started for individual
+developers.
+
+**[Get started with the UI →](./guides-ui/quickstart.mdx)**
+
+
+
+
+### CLI
+
+For power users and automation. Full control over MCP servers from the command
+line.
+
+**[Get started with the CLI →](./guides-cli/quickstart.mdx)**
+
+
+
+
+### Kubernetes
+
+For teams and enterprises. Deploy and manage MCP servers at scale with the
+ToolHive Operator.
+
+**[Get started with K8s →](./guides-k8s/quickstart.mdx)**
+
+
+