diff --git a/docs/toolhive/guides-k8s/connect-clients.mdx b/docs/toolhive/guides-k8s/connect-clients.mdx index c66c5d8d..66daa23e 100644 --- a/docs/toolhive/guides-k8s/connect-clients.mdx +++ b/docs/toolhive/guides-k8s/connect-clients.mdx @@ -68,8 +68,14 @@ an Ingress resource or Gateway API. :::info[Service naming convention] The ToolHive operator automatically creates a Kubernetes Service for each -MCPServer following the naming pattern `mcp--proxy`. For example, an -MCPServer named `fetch` gets a Service named `mcp-fetch-proxy`. +MCPServer, MCPRemoteProxy, and VirtualMCPServer resource using the following +naming patterns using the resource name: + +- MCPServer: `mcp--proxy` +- MCPRemoteProxy: `mcp--remote-proxy` +- VirtualMCPServer: `vmcp-` + +For example, an MCPServer named `fetch` gets a Service named `mcp-fetch-proxy`. ::: @@ -412,7 +418,7 @@ spec: - fetch-mcp.example.com # Change to your domain rules: - backendRefs: - - name: mcp-fetch-proxy # Format: mcp--proxy + - name: mcp-fetch-proxy # Format: mcp--proxy port: 8080 # This matches the proxyPort ``` @@ -450,7 +456,7 @@ spec: type: ReplacePrefixMatch replacePrefixMatch: / backendRefs: - - name: mcp-fetch-proxy # Format: mcp--proxy + - name: mcp-fetch-proxy # Format: mcp--proxy port: 8080 # This matches the proxyPort # Another MCP server - matches: @@ -532,7 +538,7 @@ spec: type: ReplacePrefixMatch replacePrefixMatch: / backendRefs: - - name: mcp-fetch-proxy # Format: mcp--proxy + - name: mcp-fetch-proxy # Format: mcp--proxy port: 8080 # This matches the proxyPort - matches: - path: @@ -703,16 +709,22 @@ and secure than routing through an external Ingress. ### Service DNS names -Each MCPServer automatically gets a Kubernetes Service that other pods can use -to connect. The service name follows the pattern `mcp--proxy`, and the -full DNS name follows the standard Kubernetes pattern: +Each MCPServer, MCPRemoteProxy, or VirtualMCPServer automatically gets a +Kubernetes Service that other pods can use to connect using the following naming +patterns: + +- MCPServer: `mcp--proxy` +- MCPRemoteProxy: `mcp--remote-proxy` +- VirtualMCPServer: `vmcp-` + +The full DNS name follows the standard Kubernetes pattern: ```text -mcp--proxy..svc.cluster.local: +..svc.cluster.local: ``` For example, if you have an MCPServer named `fetch` in the `toolhive-system` -namespace with `proxyPort: 8080`, the full URL would be: +namespace with `proxyPort: 8080`, the full URL is: ```text http://mcp-fetch-proxy.toolhive-system.svc.cluster.local:8080 @@ -877,8 +889,8 @@ MCP server usage and performance. external MCP servers - [Client compatibility](../reference/client-compatibility.mdx) - Supported MCP clients and configuration -- [Kubernetes CRD reference](../reference/crd-spec.mdx) - Full MCPServer - specification +- [Kubernetes CRD reference](../reference/crd-spec.mdx#apiv1alpha1mcpserver) - + Full MCPServer specification - [Configure secure ingress tutorial](../tutorials/k8s-ingress-ngrok.mdx) - Complete tutorial using ngrok and Gateway API @@ -905,7 +917,7 @@ Common causes: - **Proxy pod not running**: Ensure the MCPServer resource was created successfully - **Wrong service name**: The Ingress backend service name must follow the - pattern `mcp--proxy` + 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 @@ -1028,8 +1040,8 @@ Common causes: verify it exists - **Wrong port**: Ensure you're using the `proxyPort` value from the MCPServer spec -- **Wrong service name**: Remember the service name is `mcp--proxy`, not - just `` +- **Wrong service name**: Remember the service name follows the naming + conventions defined above diff --git a/docs/toolhive/guides-k8s/customize-tools.mdx b/docs/toolhive/guides-k8s/customize-tools.mdx index 7eb2c2ba..b906f636 100644 --- a/docs/toolhive/guides-k8s/customize-tools.mdx +++ b/docs/toolhive/guides-k8s/customize-tools.mdx @@ -106,8 +106,11 @@ use distinct tool names like `github_prod_create_pr` and ## Reference the configuration from an MCP server -Add `toolConfigRef` to your `MCPServer`. `toolConfigRef` takes precedence over -the deprecated `spec.tools` field on `MCPServer`. +Add `toolConfigRef` to the `spec` section of your MCPServer or MCPRemoteProxy +resource. + + + ```yaml {10-11} title="mcpserver-with-toolconfig.yaml" apiVersion: toolhive.stacklok.dev/v1alpha1 @@ -121,8 +124,30 @@ spec: proxyPort: 8080 toolConfigRef: name: github-tools-config + # ... other spec fields ... ``` + + + +```yaml {10-11} title="mcpremoteproxy-with-toolconfig.yaml" +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPRemoteProxy +metadata: + name: github + namespace: toolhive-system +spec: + remoteUrl: https://github.com/github/github-mcp-server + transport: streamable-http + proxyPort: 8080 + toolConfigRef: + name: github-tools-config + # ... auth config ... +``` + + + + :::note[Filtering and overrides together] When you use `toolsFilter` and `toolsOverride` together, filter by the @@ -211,6 +236,7 @@ kubectl -n toolhive-system get mcpserver github -o yaml ## Related information -- See the [Kubernetes CRD reference](../reference/crd-spec.mdx) for the full - MCPToolConfig and MCPServerSpec schemas. +- See the + [Kubernetes CRD reference](../reference/crd-spec.mdx#apiv1alpha1mcptoolconfig) + for the full MCPToolConfig and MCPServerSpec schemas. - Learn how to [run the MKP server in Kubernetes](../guides-mcp/k8s.mdx). diff --git a/docs/toolhive/guides-k8s/deploy-registry.mdx b/docs/toolhive/guides-k8s/deploy-registry.mdx index 9128e598..3503d291 100644 --- a/docs/toolhive/guides-k8s/deploy-registry.mdx +++ b/docs/toolhive/guides-k8s/deploy-registry.mdx @@ -617,8 +617,8 @@ feature. ## Related information -- [Kubernetes CRD reference](../reference/crd-spec.mdx) - Reference for the - `MCPRegistry` Custom Resource Definition (CRD) +- [Kubernetes CRD reference](../reference/crd-spec.mdx#apiv1alpha1mcpregistry) - + Reference for the `MCPRegistry` Custom Resource Definition (CRD) - [Deploy the operator using Helm](./deploy-operator-helm.mdx) - Install the ToolHive operator - [Database configuration](../guides-registry/database.mdx) - Configure diff --git a/docs/toolhive/guides-k8s/index.mdx b/docs/toolhive/guides-k8s/index.mdx index 88b07f22..7aeb98b6 100644 --- a/docs/toolhive/guides-k8s/index.mdx +++ b/docs/toolhive/guides-k8s/index.mdx @@ -18,9 +18,9 @@ in multi-user environments. :::info[Experimental] The Kubernetes operator is still under active development and isn't recommended -for production use cases yet. Specifically, the `MCPServer` Custom Resource -Definition (CRD) is still in an alpha state so breaking changes to the spec and -its capabilities are possible. +for production use cases yet. Specifically, the Custom Resource Definitions +(CRDs) are still in an alpha state so breaking changes to the spec and +capabilities are possible. ::: diff --git a/docs/toolhive/guides-k8s/intro.mdx b/docs/toolhive/guides-k8s/intro.mdx index b6b78f97..490e23d3 100644 --- a/docs/toolhive/guides-k8s/intro.mdx +++ b/docs/toolhive/guides-k8s/intro.mdx @@ -10,9 +10,9 @@ deployment and management. :::info[Experimental] The Kubernetes operator is still under active development and isn't recommended -for production use cases yet. Specifically, the `MCPServer` Custom Resource -Definition (CRD) is still in an alpha state so breaking changes to the spec and -its capabilities are possible. +for production use cases yet. Specifically, the Custom Resource Definitions +(CRDs) are still in an alpha state so breaking changes to the spec and +capabilities are possible. See the [ToolHive Operator quickstart tutorial](../tutorials/quickstart-k8s.mdx) to get started quickly using a local kind cluster. We'd love for you to try it @@ -22,9 +22,14 @@ out and send feedback! ## Overview -The operator introduces a new Custom Resource Definition (CRD) called -`MCPServer` that represents an MCP server in Kubernetes. When you create an -`MCPServer` resource, the operator automatically: +The operator introduces new Custom Resource Definitions (CRDs) into your +Kubernetes cluster. The primary CRDs for MCP server workloads are `MCPServer`, +which represents a single MCP server running in Kubernetes, `MCPRemoteProxy`, +which represents an MCP server running outside the cluster that is proxied by +ToolHive, and `VirtualMCPServer`, which represents a virtual MCP server gateway +that aggregates multiple backend MCP servers. + +When you create an `MCPServer` resource, the operator automatically: 1. Creates a Deployment to run the MCP server 2. Sets up a Service to expose the MCP server @@ -49,8 +54,12 @@ flowchart TB Client["MCP Client
[ex: Copilot]"] -- http --> Ingress ``` -The diagram shows how clients connect to MCP servers through an Ingress. To -learn how to expose your MCP servers and connect clients, see +`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 @@ -59,5 +68,8 @@ learn how to expose your MCP servers and connect clients, see Kubernetes cluster. Helm simplifies the installation process and lets you manage the operator using Helm charts. -Once the operator is installed, you can create and manage MCP servers using the -[`MCPServer` custom resource](./run-mcp-k8s.mdx). +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/docs/toolhive/guides-k8s/logging.mdx b/docs/toolhive/guides-k8s/logging.mdx index cdc1bb51..c267ed79 100644 --- a/docs/toolhive/guides-k8s/logging.mdx +++ b/docs/toolhive/guides-k8s/logging.mdx @@ -1,5 +1,5 @@ --- -title: Set up logging +title: Audit logging description: Configure and manage logging for ToolHive in Kubernetes environments --- @@ -79,6 +79,9 @@ 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: + + + ```yaml {11-12} apiVersion: toolhive.stacklok.dev/v1alpha1 kind: MCPServer @@ -94,6 +97,49 @@ spec: enabled: true ``` + + + +```yaml {11-12} +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: MCPRemoteProxy +metadata: + name: + namespace: toolhive-system +spec: + remoteUrl: + # ... other spec fields ... + + # Enable audit logging + audit: + enabled: true +``` + + + + +```yaml {11-14} +apiVersion: toolhive.stacklok.dev/v1alpha1 +kind: VirtualMCPServer +metadata: + name: + namespace: toolhive-system +spec: + config: + groupRef: + + # Enable audit logging + audit: + enabled: true + includeRequestData: true + includeResponseData: true + + # ... other configs ... +``` + + + + ToolHive writes audit logs to stdout alongside standard application logs. Your log collector can differentiate them using the `audit_id` field or by filtering for `"msg": "audit_event"`. @@ -101,7 +147,8 @@ for `"msg": "audit_event"`. ### Audit log format When audit logging is enabled, each MCP operation generates a structured audit -event: +event. For example, here is a sample audit log entry for a tool execution +request from an MCPServer resource: ```json { diff --git a/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx b/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx index b179074a..7019d5da 100644 --- a/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx +++ b/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx @@ -655,8 +655,8 @@ feature in the ToolHive Registry Server. ## Related information -- [Kubernetes CRD reference](../reference/crd-spec.mdx) - Full MCPRemoteProxy - specification +- [Kubernetes CRD reference](../reference/crd-spec.mdx#apiv1alpha1mcpremoteproxy) - + Full MCPRemoteProxy specification - [Deploy the operator using Helm](./deploy-operator-helm.mdx) - Install the ToolHive operator - [Run MCP servers in Kubernetes](./run-mcp-k8s.mdx) - Deploy local MCP servers diff --git a/docs/toolhive/guides-k8s/run-mcp-k8s.mdx b/docs/toolhive/guides-k8s/run-mcp-k8s.mdx index c15b7dcc..245534fa 100644 --- a/docs/toolhive/guides-k8s/run-mcp-k8s.mdx +++ b/docs/toolhive/guides-k8s/run-mcp-k8s.mdx @@ -208,7 +208,7 @@ This approach provides: 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.mdx). +[Kubernetes CRD reference](../reference/crd-spec.mdx#apiv1alpha1mcpserver). Below are some common configurations. @@ -461,8 +461,8 @@ feature in the ToolHive Registry Server. ## Related information -- [Kubernetes CRD reference](../reference/crd-spec.mdx) - Reference for the - `MCPServer` Custom Resource Definition (CRD) +- [Kubernetes CRD reference](../reference/crd-spec.mdx#apiv1alpha1mcpserver) - + Reference for the `MCPServer` Custom Resource Definition (CRD) - [Deploy the operator using Helm](./deploy-operator-helm.mdx) - Install the ToolHive operator - [Build MCP containers](../guides-cli/build-containers.mdx) - Create custom MCP diff --git a/docs/toolhive/guides-k8s/telemetry-and-metrics.mdx b/docs/toolhive/guides-k8s/telemetry-and-metrics.mdx index d46557d1..2c1b6296 100644 --- a/docs/toolhive/guides-k8s/telemetry-and-metrics.mdx +++ b/docs/toolhive/guides-k8s/telemetry-and-metrics.mdx @@ -21,14 +21,14 @@ the [observability overview](../concepts/observability.mdx). ## Enable telemetry You can enable telemetry when deploying an MCP server by specifying Telemetry -configuration in the `MCPServer` custom resource. +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 +```yaml {12} apiVersion: toolhive.stacklok.dev/v1alpha1 -kind: MCPServer +kind: MCPServer # or MCPRemoteProxy metadata: name: gofetch namespace: toolhive-system @@ -37,8 +37,7 @@ spec: transport: streamable-http proxyPort: 8080 mcpPort: 8080 - ... - ... + # ... other spec fields ... telemetry: openTelemetry: enabled: true @@ -49,7 +48,7 @@ spec: enabled: true tracing: enabled: true - samplingRate: "0.05" + samplingRate: '0.05' prometheus: enabled: true ``` @@ -283,7 +282,7 @@ Telemetry adds minimal overhead when properly configured: Step-by-step guide to set up a local observability stack - [Telemetry and monitoring concepts](../concepts/observability.mdx) - Overview of ToolHive's observability architecture -- [Kubernetes CRD reference](../reference/crd-spec.mdx) - Reference for the - `MCPServer` Custom Resource Definition (CRD) +- [Kubernetes CRD reference](../reference/crd-spec.mdx#apiv1alpha1mcpserver) - + Reference for the `MCPServer` Custom Resource Definition (CRD) - [Deploy the operator using Helm](./deploy-operator-helm.mdx) - Install the ToolHive operator diff --git a/docs/toolhive/guides-vmcp/configuration.mdx b/docs/toolhive/guides-vmcp/configuration.mdx index 15430c20..d1d6df29 100644 --- a/docs/toolhive/guides-vmcp/configuration.mdx +++ b/docs/toolhive/guides-vmcp/configuration.mdx @@ -5,14 +5,14 @@ description: How to configure a Virtual MCP Server for common scenarios. This guide covers common configuration patterns for vMCP using the VirtualMCPServer resource. For a complete field reference, see the -[VirtualMCPServer CRD specification](../reference/crd-spec.mdx#virtualmcpserver). +[VirtualMCPServer CRD specification](../reference/crd-spec.mdx#apiv1alpha1virtualmcpserver). ## Create an MCPGroup Before creating a VirtualMCPServer, you need an -[MCPGroup](../reference/crd-spec.mdx#mcpgroup) to organize the backend MCP -servers. An MCPGroup is a logical container that groups related MCPServer -resources together. +[MCPGroup](../reference/crd-spec.mdx#apiv1alpha1mcpgroup) to organize the +backend MCP servers. An MCPGroup is a logical container that groups related +MCPServer resources together. Create a basic MCPGroup: @@ -106,7 +106,7 @@ feature in the ToolHive Registry Server. ## Related information -- [VirtualMCPServer CRD specification](../reference/crd-spec.mdx#virtualmcpserver) +- [VirtualMCPServer CRD specification](../reference/crd-spec.mdx#apiv1alpha1virtualmcpserver) - [Introduction to vMCP](./intro.mdx) - [Tool aggregation](./tool-aggregation.mdx) - [Composite tools](./composite-tools.mdx) diff --git a/sidebars.ts b/sidebars.ts index 3af9d5a6..34d3158a 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -154,8 +154,8 @@ const sidebars: SidebarsConfig = { 'toolhive/guides-k8s/intro', 'toolhive/guides-k8s/deploy-operator-helm', 'toolhive/guides-k8s/run-mcp-k8s', - 'toolhive/guides-k8s/connect-clients', 'toolhive/guides-k8s/remote-mcp-proxy', + 'toolhive/guides-k8s/connect-clients', 'toolhive/guides-k8s/customize-tools', 'toolhive/guides-k8s/telemetry-and-metrics', 'toolhive/guides-k8s/logging',