Document the CLI and k8s token exchange setup in guides #306
Conversation
Document how to configure RFC 8693 token exchange so MCP servers can authenticate to backend APIs using short-lived tokens instead of embedded secrets. Includes IdP configuration steps, CLI parameters, and an Okta example with annotated key points. Fixes: #240
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull Request Overview
This PR adds comprehensive documentation for configuring token exchange to enable backend authentication in ToolHive. Token exchange allows MCP servers to obtain short-lived, properly scoped tokens for authenticating to backend services, replacing the need for embedded secrets.
- Adds two new guides: one for CLI-based token exchange setup and one for Kubernetes deployments
- Updates sidebar navigation to include the new token exchange guides in appropriate sections
- Provides detailed configuration steps, examples, and troubleshooting guidance for both deployment models
Reviewed Changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| sidebars.ts | Adds token exchange guide entries to both CLI and Kubernetes sections of the navigation |
| docs/toolhive/guides-cli/token-exchange.mdx | New guide documenting CLI-based token exchange configuration with IdP setup steps and examples |
| docs/toolhive/guides-k8s/token-exchange-k8s.mdx | New guide documenting Kubernetes-based token exchange using CRDs with complete YAML examples |
Document how to configure RFC 8693 token exchange for MCP servers in Kubernetes using the ToolHive Operator. Covers MCPExternalAuthConfig resource creation, Secret management, and MCPServer configuration with an Okta example. Fixes: #240
danbarr
left a comment
danbarr
left a comment
There was a problem hiding this comment.
These look really good. I noted a few questions and optional suggestions.
| oidcConfig: | ||
| type: inline |
There was a problem hiding this comment.
Is the resourceUrl needed here too, to override the internal service URL with whatever the client-facing URL will be (if it's being exposed outside the cluster)?
| kubectl get mcpserver -n toolhive-system my-mcp-server | ||
| ``` | ||
|
|
||
| 2. Connect to the MCP server with a client that supports authentication |
There was a problem hiding this comment.
Do we need a step before this, to (optionally) expose the Service outside the cluster?
Also, it might be nice to have slightly more detail here - will the client need any info like the id/secret? Maybe a quick note on how to wire it up using the ToolHive UI or CLI? (I plan to add a general "Connecting clients" guide, but anything specific to this particular config would help here)
|
|
||
| To confirm token exchange is working: | ||
|
|
||
| 1. Connect to the MCP server with a client that supports authentication |
There was a problem hiding this comment.
Since thv run is used in this case, I guess any clients configured using thv client setup should already be configured?
| The MCP server that ToolHive fronts must accept a per-request authentication | ||
| token. Specifically, the server should: |
There was a problem hiding this comment.
Any examples we can name? MCP Toolbox for Databases?
| --token-exchange-client-secret-file /path/to/client-secret \ | ||
| --token-exchange-audience backend-api \ | ||
| --token-exchange-scopes "api:read,api:write" \ | ||
| <server-name> |
There was a problem hiding this comment.
| <server-name> | |
| <SERVER_NAME_OR_IMAGE> |
| --token-exchange-client-secret <TOOLHIVE_CLIENT_SECRET> \ | ||
| --token-exchange-audience <BACKEND_AUDIENCE> \ | ||
| --token-exchange-scopes <BACKEND_SCOPES> \ | ||
| <server-name> |
There was a problem hiding this comment.
| <server-name> | |
| <SERVER_NAME_OR_IMAGE> |
Description
In addition to the concept guide about back end auth, adds a CLI and a k8s guide. Because a fair amount of config is on the IDP side which is inherently IDP-specific, I kept the guides quite generic.
Related issues/PRs
#240
Screenshots
N/A
Merge checklist
Content
sidebars.ts) updated for added, deleted, reordered, or renamed filesvercel.jsonfor moved, renamed, or deleted pages (i.e., if the URL slug changed)Reviews