From db438962092c444d3b734b70644bc7a2694418a5 Mon Sep 17 00:00:00 2001 From: Radoslav Dimitrov Date: Wed, 29 Apr 2026 20:56:53 -0400 Subject: [PATCH] docs: document GitHub OIDC audience binding for self-hosters and CI users (#1230) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary Follow-up to #1229. Three small doc additions so the new audience requirement is discoverable without reading the source: - `.env.example` lists `MCP_REGISTRY_GITHUB_OIDC_AUDIENCE` alongside the other registry env vars, with a note that the value must match the scheme+host that publishers pass via `--registry`. - The publisher CLI reference (`docs/reference/cli/commands.md`) explains that the CLI derives the audience from `--registry` and that self-hosters must set the matching env var on the registry side. - The GitHub Actions troubleshooting table (`docs/modelcontextprotocol-io/github-actions.mdx`) maps the new `invalid audience` error to the user-facing fix (upgrade `mcp-publisher`). No code changes — docs only. ## Test plan - [ ] CI green (markdown lint / link checks if any) - [ ] Eyeball-render the troubleshooting table on the modelcontextprotocol.io preview to confirm the new row formats correctly 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (1M context) --- .env.example | 8 ++++++++ docs/modelcontextprotocol-io/github-actions.mdx | 1 + docs/reference/cli/commands.md | 7 +++++++ 3 files changed, 16 insertions(+) diff --git a/.env.example b/.env.example index bfadfd4..786fc1b 100644 --- a/.env.example +++ b/.env.example @@ -27,6 +27,14 @@ MCP_REGISTRY_JWT_PRIVATE_KEY=bb2c6b424005acd5df47a9e2c87f446def86dd740c888ea3efb # This should be disabled in prod MCP_REGISTRY_ENABLE_ANONYMOUS_AUTH=false +# GitHub OIDC token exchange (for `mcp-publisher login github-oidc`) +# Expected `aud` claim on incoming GitHub Actions OIDC tokens. Must equal the +# scheme + host that publishers pass via `--registry` (e.g. `https://registry.example.com`). +# The publisher CLI derives the audience from `--registry` automatically; the server +# rejects all OIDC exchanges if this is unset, so set it on every deployment that +# accepts GitHub Actions publishes. +MCP_REGISTRY_GITHUB_OIDC_AUDIENCE= + # Google Cloud Identity OIDC configuration for admin access # Enable OIDC authentication for @modelcontextprotocol.io admin accounts MCP_REGISTRY_OIDC_ENABLED=false diff --git a/docs/modelcontextprotocol-io/github-actions.mdx b/docs/modelcontextprotocol-io/github-actions.mdx index 311b28f..0da50cd 100644 --- a/docs/modelcontextprotocol-io/github-actions.mdx +++ b/docs/modelcontextprotocol-io/github-actions.mdx @@ -220,6 +220,7 @@ The workflow will run tests, build the package, publish the package to npm, and | Error Message | Action | | --- | --- | | "Authentication failed" | Ensure `id-token: write` permission is set for OIDC, or check secrets. | +| "invalid audience" | Your `mcp-publisher` binary is too old for this registry deployment. Re-run the install step shown above so you pick up the latest release. | | "Package validation failed" | Verify your package successfully published to the package registry (e.g., npm, PyPI), and that your package has the [necessary verification information](./package-types). | {/* prettier-ignore-end */} diff --git a/docs/reference/cli/commands.md b/docs/reference/cli/commands.md index 0f44b7b..e077019 100644 --- a/docs/reference/cli/commands.md +++ b/docs/reference/cli/commands.md @@ -72,6 +72,13 @@ mcp-publisher login github-oidc [--registry=URL] - Requires `id-token: write` permission in workflow - No browser interaction needed +The CLI derives the OIDC `aud` claim from `--registry` (scheme + host, e.g. +`https://registry.modelcontextprotocol.io`) so tokens are bound to the specific +deployment they were minted for. Self-hosters must set +`MCP_REGISTRY_GITHUB_OIDC_AUDIENCE` on the registry to the matching value; +publishers running an older `mcp-publisher` will fail with `invalid audience` +and need to upgrade. + Also see [the guide to publishing from GitHub Actions](../../modelcontextprotocol-io/github-actions.mdx). #### DNS Verification