[Enhancement]: Decide house convention for OIDC audience values in docs examples

[danbarr]

Page or section

Multiple pages use an incoming client-authentication audience, with an inconsistent style (resource-URL vs short logical name):

• Resource-URL form: guides-vmcp/authentication.mdx, guides-vmcp/embedded-auth-server-vmcp.mdx, guides-k8s/embedded-auth-server-k8s.mdx, guides-k8s/mcp-server-entry.mdx, parts of guides-k8s/remote-mcp-proxy.mdx, guides-mcp/notion-remote.mdx.
• Short logical name: guides-vmcp/configuration.mdx (my-vmcp, context7-proxy), guides-vmcp/backend-discovery.mdx (engineering-vmcp), guides-vmcp/failure-handling.mdx (my-vmcp), guides-vmcp/optimizer.mdx (vmcp-example), guides-k8s/auth-k8s.mdx (weather-server), guides-k8s/connect-clients.mdx (my-audience), other remote-mcp-proxy.mdx examples (mcp-proxy).

What could be better

PR #1023 (vMCP auth docs restructure) standardized the vMCP auth pages' incoming client-auth audience on the resource-URL form (https://mcp.example.com/mcp), aligned 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. That surfaced a pre-existing style inconsistency: other pages use short logical names.

This is a consistency/style question, not a correctness bug. Every example is already unique per server (the rule the docs state), and aud is an opaque string that does not have to be a URL. The question is purely which style to teach consistently.

Out of scope (a different kind of audience, leave as-is): Kubernetes service-account token audiences (toolhive, registry-server); token-exchange target audiences (backend-api, mcp-server); registry incoming audiences (registry-api); IdP-specific values that reflect what the provider actually emits (Okta api://default, Azure api://<client-id>, Google client-ID audiences).

Proposed improvement

Needs an auth SME decision before we normalize anything:

1. For the incoming client-auth audience, should docs examples standardize on the resource-URL form (spec-aligned) or short logical names?
2. If URL form: normalize docs-wide, or only where it's the natural fit?
3. Any nuance to capture in the canonical auth pages (for example, shared vs. per-server audiences, and how SSO, not shared audiences, is what reduces re-auth)?

Additional context

See the audience/resource-URL discussion on #1023. Relevant specs: RFC 8707 (Resource Indicators), RFC 9728 (Protected Resource Metadata).

[danbarr]

@jhrozek do we have a convention here?

[jhrozek]

@jhrozek do we have a convention here?

I don't think we have a convention but I have a preference :-) to use URLs (e.g. https://mcp.example.com). The reasons are: 1) the MCP spec mandates that a client requests a token with resource=$server_url and then the server checks the aud matches server's expected audience. So in fact the resource and audience should match 2) I checked WorkOS' MCP guide and that's what they do as well.

I think the out of scopes are well scoped as well