Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/upstream-projects.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ projects:

- id: toolhive
repo: stacklok/toolhive
version: v0.61.0
version: v0.64.0
# toolhive is a monorepo covering the CLI, the Kubernetes
# operator, and the vMCP gateway. It also introduces cross-
# cutting features that land in concepts/, integrations/,
Expand Down
5 changes: 5 additions & 0 deletions docs/toolhive/guides-cli/webhooks.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -351,6 +351,11 @@ webhook endpoint:
- `ignore` allows the tool call through. Use this for non-critical webhooks like
logging or enrichment, where availability is not a hard requirement.

The failure policy covers errors reaching or reading from the webhook, such as
timeouts, network errors, and invalid responses. If ToolHive fails before it
sends the request, for example because it can't resolve the HMAC signing secret
or build the request payload, it rejects the request under either policy.

:::warning

A `422 Unprocessable Entity` response from a webhook is always treated as a
Expand Down
5 changes: 4 additions & 1 deletion docs/toolhive/guides-k8s/auth-k8s.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -224,7 +224,10 @@ kubectl get mcpserver <YOUR_SERVER_NAME> -n toolhive-system \
```

If the ConfigMap is missing or the key isn't found, the condition reports a
`False` status with a reason of `CABundleRefNotFound` or `CABundleRefInvalid`.
`False` status with a reason of `CABundleRefNotFound` or `CABundleRefInvalid`. A
VirtualMCPServer whose `incomingAuth.oidcConfigRef` points at the same
`MCPOIDCConfig` reports the same condition, so you can check it with
`kubectl get virtualmcpserver` in the same way.

### Authenticate Kubernetes service-to-service traffic

Expand Down
51 changes: 51 additions & 0 deletions docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -219,6 +219,7 @@ with a generic "authorization header required" error.
| `upstreamProviders` | Configuration for upstream identity providers. MCPServer and MCPRemoteProxy support one provider; VirtualMCPServer supports multiple providers for sequential authentication. |
| `cimd` | Optional Client ID Metadata Document (CIMD) configuration. When `cimd.enabled` is `true`, the auth server accepts HTTPS URLs as `client_id` values and resolves them via CIMD, letting clients (for example, VS Code) authenticate without prior Dynamic Client Registration. See [Enable CIMD for zero-registration clients](#enable-cimd-for-zero-registration-clients). |
| `baselineClientScopes` | Optional list of OAuth 2.0 scopes merged into every DCR-registered client's scope set. Use this when MCP clients register with a narrowed `scope` field but then request wider scopes at `/oauth/authorize`. See [Enable baseline scopes for DCR clients](#enable-baseline-scopes-for-dcr-clients). |
| `tlsListener` | Optional. Serves the authorization server's OAuth endpoints over HTTPS on port 8443, using a certificate and private key from a Secret. See [Serve the authorization server over TLS](#serve-the-authorization-server-over-tls). |
| `disableUpstreamTokenInjection` | Optional. When `true`, the embedded auth server authenticates clients normally but the proxy strips `Authorization`, `Cookie`, and `Proxy-Authorization` from forwarded requests instead of swapping the JWT for an upstream token. Use this for public backends (such as documentation servers) that you still want to gate behind client auth. Cannot be combined with `tokenExchange`, `awsSts`, or OBO (Stacklok Enterprise) on the same workload, since each would re-add credentials after the strip. |

## Step 5: Create the MCPOIDCConfig and MCPServer resources
Expand Down Expand Up @@ -394,6 +395,56 @@ kubectl create secret generic redis-acl-secret \
For a complete walkthrough including deploying Redis Sentinel from scratch, see
[Redis session storage](./redis-session-storage.mdx).

## Serve the authorization server over TLS

By default, the embedded authorization server shares the proxy's plain HTTP
port, and you terminate TLS at an ingress or gateway in front of it. To have the
pod serve the authorization server's OAuth endpoints over HTTPS itself, add a
`tlsListener` block at `spec.embeddedAuthServer.tlsListener`. The listener runs
on port 8443 alongside the HTTP port. MCP traffic, health probes, and metrics
stay on the HTTP port.

Create a TLS Secret with the certificate and private key in PEM format:

```bash
kubectl create secret tls auth-server-tls \
--namespace toolhive-system \
--cert=tls.crt \
--key=tls.key
```

Then reference both keys from the `MCPExternalAuthConfig`. Both
`certificateSecretRef` and `privateKeySecretRef` are required:

```yaml title="MCPExternalAuthConfig: TLS listener"
spec:
type: embeddedAuthServer
embeddedAuthServer:
# ...
tlsListener:
certificateSecretRef:
name: auth-server-tls
key: tls.crt
privateKeySecretRef:
name: auth-server-tls
key: tls.key
```

When `tlsListener` is set, the operator adds a container port named `https-auth`
and a Service port 8443 with `appProtocol: https` to each MCPServer or
MCPRemoteProxy that references the config. The listener accepts TLS 1.2 or
later. When the certificate in the Secret is renewed, the listener picks up the
new certificate without a pod restart.

Because the TLS listener owns port 8443, set the workload's `proxyPort` to a
different port. If both use 8443, the operator marks the workload `Failed` and
reports the conflict in its status conditions.

A VirtualMCPServer accepts the same block at
`spec.authServerConfig.tlsListener`. See
[Serve the authorization server over TLS](../guides-vmcp/embedded-auth-server-vmcp.mdx#serve-the-authorization-server-over-tls)
in the vMCP guide.

## Configure MCP client registration

MCP clients must identify themselves to the embedded authorization server. The
Expand Down
1 change: 1 addition & 0 deletions docs/toolhive/guides-vmcp/delegate-agent-identity.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -318,5 +318,6 @@ must register again.
| `invalid_grant`: "This client is not authorized to exchange subject tokens from the external actor's issuer." | The authenticated client isn't in `issuerPolicies[].allowedDelegateClients` for the issuer that minted the subject token. |
| `invalid_grant`: "The subject token was issued to a different client." | The subject token's own `client_id` claim doesn't match the authenticated delegate client, and the client isn't in `allowedDelegateClients`. |
| `invalid_request`: "The subject token is invalid or could not be verified." | The subject token failed signature, issuer, or audience validation against every configured `trustedIssuers` entry. |
| `invalid_target`: "The client is not permitted to request audience ..." | The `audience` parameter on the exchange request isn't in the delegate client's `audiences` list. Request one of the listed audiences, or add the audience to `delegateClients[].audiences`. |
| CRD rejected: `issuerPolicies[]: allowedDelegateClients: Required value` | An `inboundGrants.tokenExchange.issuerPolicies` entry is missing `allowedDelegateClients`. Add it. |
| CRD rejected: "delegateClients with an HTTP issuer require insecureAllowConfidentialOverLoopbackHTTP to be explicitly enabled" | A delegate client uses a plain-HTTP issuer. Use an `https://` issuer, or for local development set `insecureAllowConfidentialOverLoopbackHTTP: true` with a loopback issuer. |
13 changes: 13 additions & 0 deletions docs/toolhive/guides-vmcp/embedded-auth-server-vmcp.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -669,6 +669,19 @@ registration orphaned. For production, configure Redis storage by adding a
[Redis session storage](../guides-k8s/redis-session-storage.mdx) for a complete
walkthrough.

## Serve the authorization server over TLS

To have the vMCP pod serve the authorization server's OAuth endpoints over HTTPS
itself, add a `tlsListener` block to `authServerConfig` that references a
PEM-encoded certificate and private key in a Secret. The listener runs on port
8443, and the operator adds it to the vMCP Service as port 8443 with
`appProtocol: https`. MCP traffic stays on the HTTP port. If the Service uses
`serviceType: LoadBalancer` or `NodePort`, port 8443 is reachable from outside
the cluster and serves the same authorization server routes as the HTTP port.
See
[Serve the authorization server over TLS](../guides-k8s/embedded-auth-server-k8s.mdx#serve-the-authorization-server-over-tls)
for the field layout and Secret setup.

## Forward user tokens to backends

The embedded auth server stores each user's upstream tokens after login. Three
Expand Down
4 changes: 2 additions & 2 deletions docs/toolhive/reference/cli/thv.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,8 @@ thv [flags]
### Options

```
--debug Enable debug mode
-h, --help help for thv
--debug[=true|false] Enable debug mode
-h, --help[=true|false] help for thv
```

### SEE ALSO
Expand Down
4 changes: 2 additions & 2 deletions docs/toolhive/reference/cli/thv_ai-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,13 @@ commands, agents, skills, hooks, and server declarations.
### Options

```
-h, --help help for ai-plugin
-h, --help[=true|false] help for ai-plugin
```

### Options inherited from parent commands

```
--debug Enable debug mode
--debug[=true|false] Enable debug mode
```

### SEE ALSO
Expand Down
6 changes: 3 additions & 3 deletions docs/toolhive/reference/cli/thv_ai-plugin_build.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,14 @@ thv ai-plugin build [path] [flags]
### Options

```
-h, --help help for build
-t, --tag string OCI tag for the built artifact
-h, --help[=true|false] help for build
-t, --tag string OCI tag for the built artifact
```

### Options inherited from parent commands

```
--debug Enable debug mode
--debug[=true|false] Enable debug mode
```

### SEE ALSO
Expand Down
6 changes: 3 additions & 3 deletions docs/toolhive/reference/cli/thv_ai-plugin_builds.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,14 +24,14 @@ thv ai-plugin builds [flags]
### Options

```
--format string Output format (json, text) (default "text")
-h, --help help for builds
--format string Output format (json, text) (default "text")
-h, --help[=true|false] help for builds
```

### Options inherited from parent commands

```
--debug Enable debug mode
--debug[=true|false] Enable debug mode
```

### SEE ALSO
Expand Down
4 changes: 2 additions & 2 deletions docs/toolhive/reference/cli/thv_ai-plugin_builds_remove.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,13 +24,13 @@ thv ai-plugin builds remove <tag> [flags]
### Options

```
-h, --help help for remove
-h, --help[=true|false] help for remove
```

### Options inherited from parent commands

```
--debug Enable debug mode
--debug[=true|false] Enable debug mode
```

### SEE ALSO
Expand Down
4 changes: 2 additions & 2 deletions docs/toolhive/reference/cli/thv_ai-plugin_info.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,15 +25,15 @@ thv ai-plugin info [plugin-name] [flags]

```
--format string Output format (json, text) (default "text")
-h, --help help for info
-h, --help[=true|false] help for info
--project-root string Project root path for project-scoped plugins
--scope string Filter by scope (user, project)
```

### Options inherited from parent commands

```
--debug Enable debug mode
--debug[=true|false] Enable debug mode
```

### SEE ALSO
Expand Down
18 changes: 9 additions & 9 deletions docs/toolhive/reference/cli/thv_ai-plugin_install.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,20 +29,20 @@ thv ai-plugin install [plugin-name] [flags]
### Options

```
--allow-unsigned Allow installing a project-scoped plugin without a verified signature (recorded in the lock file)
--clients string Comma-separated target client apps (e.g. claude-code,codex), or "all" for every available client
--force Overwrite existing plugin directory
--group string Group to add the plugin to after installation
-h, --help help for install
--project-root string Project root path for project-scoped installs
--public-key string Path to the cosign public key (cosign.pub) a key-pair-signed plugin must verify against. Required the first time such a plugin is installed project-scoped; the key is then pinned in the lock file and reused automatically
--scope string Installation scope (user, project) (default "user")
--allow-unsigned[=true|false] Allow installing a project-scoped plugin without a verified signature (recorded in the lock file)
--clients string Comma-separated target client apps (e.g. claude-code,codex), or "all" for every available client
--force[=true|false] Overwrite existing plugin directory
--group string Group to add the plugin to after installation
-h, --help[=true|false] help for install
--project-root string Project root path for project-scoped installs
--public-key string Path to the cosign public key (cosign.pub) a key-pair-signed plugin must verify against. Required the first time such a plugin is installed project-scoped; the key is then pinned in the lock file and reused automatically
--scope string Installation scope (user, project) (default "user")
```

### Options inherited from parent commands

```
--debug Enable debug mode
--debug[=true|false] Enable debug mode
```

### SEE ALSO
Expand Down
4 changes: 2 additions & 2 deletions docs/toolhive/reference/cli/thv_ai-plugin_list.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,15 +27,15 @@ thv ai-plugin list [flags]
--client string Filter by client application
--format string Output format (json, text) (default "text")
--group string Filter by group
-h, --help help for list
-h, --help[=true|false] help for list
--project-root string Project root path for project-scoped plugins
--scope string Filter by scope (user, project)
```

### Options inherited from parent commands

```
--debug Enable debug mode
--debug[=true|false] Enable debug mode
```

### SEE ALSO
Expand Down
6 changes: 3 additions & 3 deletions docs/toolhive/reference/cli/thv_ai-plugin_push.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,16 +27,16 @@ thv ai-plugin push [reference] [flags]
### Options

```
-h, --help help for push
-h, --help[=true|false] help for push
--identity-token string OIDC identity token (or a path to a file containing one) for keyless signing. Mutually exclusive with --key. If omitted, one is acquired automatically: from the GitHub Actions OIDC token when running with id-token: write permission, otherwise via an interactive browser sign-in
--key string Path to a cosign private key to sign the pushed artifact. Requires the locally discovered ToolHive server; for a remote or manually configured API URL, use keyless signing. Encrypted keys are decrypted with COSIGN_PASSWORD read from the 'thv serve' process, which performs the signing. Consumers installing the result project-scoped must pass --public-key with the matching cosign public key the first time; distribute it alongside the artifact. Keyless signing needs no such out-of-band step, since the signer identity is verifiable from the artifact itself
--no-sign Push without signing (consumers will need an explicit unsigned exception to install project-scoped)
--no-sign[=true|false] Push without signing (consumers will need an explicit unsigned exception to install project-scoped)
```

### Options inherited from parent commands

```
--debug Enable debug mode
--debug[=true|false] Enable debug mode
```

### SEE ALSO
Expand Down
22 changes: 11 additions & 11 deletions docs/toolhive/reference/cli/thv_ai-plugin_sync.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,22 +33,22 @@ thv ai-plugin sync [flags]
### Options

```
--adopt Write lock entries for existing unmanaged project-scope installs
--allow-unsigned Record plugins as unsigned in the lock file: when adopting installs whose signature state cannot be established (--adopt), and when repairing an entry that records no trust decision and whose content is unsigned
--check Report drift without installing, writing, or removing anything
--clients string Comma-separated target client apps (e.g. claude-code,codex), or "all" for every available client
--format string Output format (json, text) (default "text")
-h, --help help for sync
--project-root string Project root path (default: auto-detected from the current directory)
--prune Remove installs no longer present in the lock file
--public-key string Path to the cosign public key used to verify key-pair-signed plugins during --adopt
--yes Skip the confirmation prompt (required when not running interactively)
--adopt[=true|false] Write lock entries for existing unmanaged project-scope installs
--allow-unsigned[=true|false] Record plugins as unsigned in the lock file: when adopting installs whose signature state cannot be established (--adopt), and when repairing an entry that records no trust decision and whose content is unsigned
--check[=true|false] Report drift without installing, writing, or removing anything
--clients string Comma-separated target client apps (e.g. claude-code,codex), or "all" for every available client
--format string Output format (json, text) (default "text")
-h, --help[=true|false] help for sync
--project-root string Project root path (default: auto-detected from the current directory)
--prune[=true|false] Remove installs no longer present in the lock file
--public-key string Path to the cosign public key used to verify key-pair-signed plugins during --adopt
--yes[=true|false] Skip the confirmation prompt (required when not running interactively)
```

### Options inherited from parent commands

```
--debug Enable debug mode
--debug[=true|false] Enable debug mode
```

### SEE ALSO
Expand Down
4 changes: 2 additions & 2 deletions docs/toolhive/reference/cli/thv_ai-plugin_uninstall.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,15 +24,15 @@ thv ai-plugin uninstall [plugin-name] [flags]
### Options

```
-h, --help help for uninstall
-h, --help[=true|false] help for uninstall
--project-root string Project root path for project-scoped plugins
--scope string Scope to uninstall from (user, project) (default "user")
```

### Options inherited from parent commands

```
--debug Enable debug mode
--debug[=true|false] Enable debug mode
```

### SEE ALSO
Expand Down
Loading
Loading