Skip to content

Commit 49589c3

Browse files
ChrisJBurnsclaude
ChrisJBurns
and
claude
authored
Part 1: Update docs for ToolHive v0.17.0 (#685)
* Update docs for ToolHive v0.17.0 Breaking changes: - Update CRD phase values from Running to Ready for MCPServer, EmbeddingServer, and MCPRegistry across quickstarts, guides, and integration pages - Migrate MCPRegistry examples from v1 flat registries[] format to v2 sources[]/registries[] with configYAML recommended path - Remove PVC source type (no longer supported) - Remove Syncing phase from MCPRegistry status documentation - Remove auto-injection note for Kubernetes discovery sources New features: - Add MCPServerEntry (zero-infrastructure catalog entries) docs to K8s intro and vMCP configuration pages - Add caBundleRef for OTLP endpoints to telemetry guide - Add authServerRef for separating embedded auth from external token exchange to auth guide - Update standalone registry server config to v2 format Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Address review findings from Copilot and code review - Fix ConfigMap source example: use volumes/volumeMounts with file path instead of CRD-level configMapRef inside configYAML - Fix URL source example: use file.url instead of CRD-level url.endpoint inside configYAML - Fix file source docs: clarify file.path and file.url are mutually exclusive within the file block - Add MCPServerEntry transport options (sse and streamable-http) - Fix resource type count: "three" → "four" in K8s intro - Align "running" → "ready" in vMCP quickstart preceding text Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix MCPServerEntry example field accuracy - Fix headerForward: use addPlaintextHeaders map instead of nonexistent headers list field - Fix externalAuthConfigRef: remove kind field that doesn't exist on ExternalAuthConfigRef (only AuthServerRef has kind) Both verified against v0.17.0 source code. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Address editorial review feedback - Replace em dash with hyphen in telemetry caBundleRef note - Fix ambiguous "Both X and Y cannot" phrasing for authServerRef - Add MCPServerEntry to MCPGroup description paragraph - Align comparison table to parallel noun phrase structure Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 21905e7 commit 49589c3

10 files changed

Lines changed: 569 additions & 316 deletions

File tree

‎docs/toolhive/guides-k8s/auth-k8s.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -652,6 +652,36 @@ spec:
652652
kubectl apply -f mcp-server-embedded-auth.yaml
653653
```
654654

655+
:::tip[Combining embedded auth with outgoing token exchange]
656+
657+
If you need both an embedded auth server for incoming client authentication
658+
**and** an outgoing token exchange (such as AWS STS) on the same MCPServer, use
659+
the dedicated `authServerRef` field instead of `externalAuthConfigRef` for the
660+
embedded auth server. This separates the two configurations so they don't
661+
compete for the same field:
662+
663+
```yaml
664+
spec:
665+
# Dedicated field for the embedded auth server
666+
authServerRef:
667+
kind: MCPExternalAuthConfig
668+
name: embedded-auth-server
669+
# Outgoing token exchange (e.g., AWS STS)
670+
externalAuthConfigRef:
671+
name: aws-sts-config
672+
kind: MCPExternalAuthConfig
673+
oidcConfig:
674+
type: inline
675+
inline:
676+
issuer: 'https://mcp.example.com'
677+
```
678+
679+
`authServerRef` and `externalAuthConfigRef` cannot both reference an
680+
`embeddedAuthServer` type. The same `authServerRef` field is available on
681+
MCPRemoteProxy resources.
682+
683+
:::
684+
655685
:::note
656686

657687
The `oidcConfig` issuer must match the `issuer` in your `MCPExternalAuthConfig`.

‎docs/toolhive/guides-k8s/intro.mdx‎

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -70,25 +70,28 @@ or Gateway. To learn how to expose your MCP servers and connect clients, see
7070
The operator introduces resource types for MCP workloads. Choose based on where
7171
your MCP server runs and how many servers you need to manage:
7272

73-
| Resource | Use when |
74-
| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
75-
| **MCPServer** | Running an MCP server as a container inside your cluster |
76-
| **MCPRemoteProxy** | Connecting to an MCP server hosted outside your cluster (SaaS tools, external APIs, remote endpoints) |
77-
| **VirtualMCPServer** | Aggregating multiple MCPServer and/or MCPRemoteProxy resources behind a single endpoint for a team or application |
73+
| Resource | Use when |
74+
| -------------------- | -------------------------------------------------------------------------------------------------------- |
75+
| **MCPServer** | Running an MCP server as a container inside your cluster |
76+
| **MCPRemoteProxy** | Connecting to an MCP server hosted outside your cluster (SaaS tools, external APIs, remote endpoints) |
77+
| **MCPServerEntry** | Declaring a remote MCP server as a lightweight catalog entry without deploying proxy pods |
78+
| **VirtualMCPServer** | Aggregating multiple MCPServer, MCPRemoteProxy, and/or MCPServerEntry resources behind a single endpoint |
7879

7980
Most teams start with `MCPServer` for container-based servers, add
8081
`MCPRemoteProxy` for external SaaS tools, and graduate to `VirtualMCPServer`
81-
when managing five or more servers or needing centralized authentication.
82+
when managing five or more servers or needing centralized authentication. Use
83+
`MCPServerEntry` instead of `MCPRemoteProxy` when you want to include a remote
84+
server in vMCP discovery without the overhead of running a proxy pod.
8285

8386
The operator also provides shared configuration CRDs that you reference from
8487
workload resources:
8588

86-
| Resource | Purpose |
87-
| ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
88-
| [**MCPOIDCConfig**](./auth-k8s.mdx#set-up-shared-oidc-configuration-with-mcpoidcconfig) | Shared OIDC authentication settings, referenced via `oidcConfigRef` |
89-
| [**MCPTelemetryConfig**](./telemetry-and-metrics.mdx#shared-telemetry-configuration-recommended) | Shared telemetry/observability settings, referenced via `telemetryConfigRef` |
90-
| [**MCPToolConfig**](./customize-tools.mdx) | Tool filtering and renaming, referenced via `toolConfigRef` |
91-
| [**MCPExternalAuthConfig**](./auth-k8s.mdx#set-up-embedded-authorization-server-authentication) | Token exchange or embedded auth server configuration, referenced via `externalAuthConfigRef` |
89+
| Resource | Purpose |
90+
| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
91+
| [**MCPOIDCConfig**](./auth-k8s.mdx#set-up-shared-oidc-configuration-with-mcpoidcconfig) | Shared OIDC authentication settings, referenced via `oidcConfigRef` |
92+
| [**MCPTelemetryConfig**](./telemetry-and-metrics.mdx#shared-telemetry-configuration-recommended) | Shared telemetry/observability settings, referenced via `telemetryConfigRef` |
93+
| [**MCPToolConfig**](./customize-tools.mdx) | Tool filtering and renaming, referenced via `toolConfigRef` |
94+
| [**MCPExternalAuthConfig**](./auth-k8s.mdx#set-up-embedded-authorization-server-authentication) | Token exchange or embedded auth server configuration, referenced via `externalAuthConfigRef` or `authServerRef` |
9295

9396
## Installation
9497

‎docs/toolhive/guides-k8s/quickstart.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -171,8 +171,8 @@ kubectl get mcpservers -n toolhive-system
171171
You should see:
172172

173173
```text
174-
NAME STATUS URL AGE
175-
fetch Running http://mcp-fetch-proxy.toolhive-system.svc.cluster.local:8080 30s
174+
NAME STATUS URL AGE
175+
fetch Ready http://mcp-fetch-proxy.toolhive-system.svc.cluster.local:8080 30s
176176
```
177177

178178
If the status is "Pending", wait a few moments and check again. If it remains

‎docs/toolhive/guides-k8s/telemetry-and-metrics.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,40 @@ spec:
146146
enabled: true
147147
```
148148

149+
#### Custom CA certificates for OTLP endpoints
150+
151+
If your OTLP collector uses TLS with certificates signed by an internal or
152+
private CA, add a `caBundleRef` to your MCPTelemetryConfig. The operator mounts
153+
the referenced ConfigMap into the pod and configures the OTLP exporters to trust
154+
the custom CA alongside the system CA pool.
155+
156+
```yaml title="telemetry-with-ca-bundle.yaml"
157+
apiVersion: toolhive.stacklok.dev/v1alpha1
158+
kind: MCPTelemetryConfig
159+
metadata:
160+
name: shared-otel
161+
namespace: toolhive-system
162+
spec:
163+
openTelemetry:
164+
enabled: true
165+
endpoint: otel-collector.internal:4318
166+
caBundleRef:
167+
configMapRef:
168+
name: otel-ca-bundle
169+
key: ca.crt
170+
tracing:
171+
enabled: true
172+
metrics:
173+
enabled: true
174+
```
175+
176+
:::note
177+
178+
`caBundleRef` cannot be used when `insecure` is set to `true` - they are
179+
mutually exclusive.
180+
181+
:::
182+
149183
### Inline telemetry configuration
150184

151185
:::warning[Deprecated]

0 commit comments

Comments
 (0)