Normalize OIDC audience examples to resource-URL form - #1064
Open
danbarr wants to merge 2 commits into
Open
Conversation
Standardize incoming client-auth audience examples on the resource-URL style, matching the MCP auth spec's Resource Indicators (RFC 8707) and Jakub's preference in #1024. Also fix a duplicate groupRef key found in the optimizer.mdx example. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR standardizes incoming client-auth audience examples across the ToolHive docs to use a resource-URL form (RFC 8707/9728-aligned), and updates related guidance to reflect that the audience should be unique per server.
Changes:
- Updated multiple OIDC
audienceexamples from short logical names (for example,my-vmcp) to resource URLs (for example,https://mcp.example.com/mcp). - Reworded
connect-clients.mdxto clarify thataudienceshould match the server’s canonical URL (resourceUrl) and be unique per server. - Removed a duplicate YAML key (
groupRef) in a vMCP optimizer example.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| docs/toolhive/guides-vmcp/optimizer.mdx | Removes duplicate YAML key and normalizes incoming OIDC audience to resource-URL form. |
| docs/toolhive/guides-vmcp/failure-handling.mdx | Normalizes incoming OIDC audience example to resource-URL form. |
| docs/toolhive/guides-vmcp/configuration.mdx | Updates vMCP OIDC audience examples to resource-URL form (including Context7 example). |
| docs/toolhive/guides-vmcp/backend-discovery.mdx | Normalizes incoming OIDC audience example to a resource URL. |
| docs/toolhive/guides-k8s/remote-mcp-proxy.mdx | Normalizes multiple audience examples; one SA-token example needs adjustment (see PR comment). |
| docs/toolhive/guides-k8s/rate-limiting.mdx | Normalizes vMCP incoming OIDC audience examples to resource-URL form. |
| docs/toolhive/guides-k8s/connect-clients.mdx | Updates examples and prose to align audience with resourceUrl and emphasize uniqueness per server. |
| docs/toolhive/guides-k8s/auth-k8s.mdx | Normalizes an incoming OIDC audience example to resource-URL form. |
That MCPOIDCConfig validates Kubernetes service account tokens, not an external IdP, so its audience is out of scope for the resource-URL normalization (per Copilot review on #1064).
danbarr
commented
Jul 28, 2026
Comment on lines
-246
to
+249
| The `audience` value should match the audience expected by your identity | ||
| provider, and is likely the same for all servers using the same authorization | ||
| server. See [Authentication and authorization](./auth-k8s.mdx) for full OIDC | ||
| setup instructions. | ||
| Set `audience` to match `resourceUrl`, the server's own canonical URL. Each | ||
| server needs a unique audience so a token issued for one server can't be | ||
| replayed against another. See [Authentication and authorization](./auth-k8s.mdx) | ||
| for full OIDC setup instructions. |
Collaborator
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Standardizes incoming client-auth
audienceexamples across the docs on the resource-URL form (e.g.https://mcp.example.com/mcp) instead of short logical names (e.g.my-vmcp,weather-server). This aligns with the MCP authorization spec's use of Resource Indicators (RFC 8707) and Protected Resource Metadata (RFC 9728), where a server's audience is its canonical resource identifier, and matches Jakub's stated preference in #1024.Files touched:
guides-vmcp/configuration.mdx,guides-vmcp/backend-discovery.mdx,guides-vmcp/failure-handling.mdx,guides-vmcp/optimizer.mdx,guides-k8s/auth-k8s.mdx,guides-k8s/connect-clients.mdx,guides-k8s/remote-mcp-proxy.mdx, andguides-k8s/rate-limiting.mdx(found with the same short-name pattern while normalizing, not in the original issue's file list).Left as-is per the issue's explicit out-of-scope list: Kubernetes service-account audiences (
toolhive), token-exchange target audiences (backend-api,mcp-server,github-api,backend), registry audiences (registry-api), and IdP-specific values (Okta, Entra, Google).In
connect-clients.mdx, also reworded a sentence claiming the audience "is likely the same for all servers using the same authorization server," which contradicted the per-server-unique resource-URL convention.Also fixed a duplicate
groupRefkey in aguides-vmcp/optimizer.mdxYAML example, found incidentally while editing that file.Type of change
Related issues/PRs
Closes #1024
Submitter checklist
Content and formatting
Reviewer checklist
Content