modelcontextprotocol/registry
Watch
1
0
Fork
You've already forked registry
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
registry/docs
History
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Radoslav Dimitrov 9e762b03c7
 docs(auth): document fine-grained PAT permission for org publishing (+ pagination-cap test) (#1435) 
Follow-up to #1383, surfaced while validating that change end-to-end
against staging.

## Why

#1383 hardened org-namespace publishing to require Owner (`admin`) role,
read via `GET /user/memberships/orgs`. Validating on staging revealed a
gap: the docs only mention the classic `read:org` scope, but a
**fine-grained PAT** (GitHub's recommended token type) needs a
*different* permission to expose org membership. Without it, GitHub
returns no org memberships for the token, so the exchange silently
grants only the personal namespace — with no hint why org publishing
"doesn't work."

This is **not** a code bug (the behavior is fail-closed and correct
given GitHub's response); it's a documentation/UX gap.

## What

- **Docs** (`authentication.mdx`, `github-actions.mdx`): spell out both
token types —
  - Classic PAT → `read:org` scope
- Fine-grained PAT → **Organization permissions → Members → Read-only**
(the equivalent), noting a fine-grained PAT is bound to a single
resource owner.
  - Also clarified `read:user` is not required.
- **Test** (`github_at_test.go`): cover the `maxOrgMembershipPages`
pagination cap — when every page is full, the exchange **fails closed**
(no token) rather than returning a possibly-truncated org grant. This
path was previously untested.
- **Comment** (`github_at.go`): qualify the `X-GitHub-SSO` 403 check as
best-effort — we have not confirmed the memberships *list* endpoint
emits that header on SSO enforcement (it may just omit the org). The
check is safe either way, but the comment no longer overstates it as a
guarantee.

## Verification (live, against staging)

Confirmed by exchanging real tokens for `rdimitrov` on
`staging.registry.modelcontextprotocol.io`:

- **Classic `read:org` PAT** across 16 real org memberships → the JWT
granted exactly the 8 **admin** orgs + personal namespace, and **zero**
of the 8 **member** orgs (incl. `stacklok`, `modelcontextprotocol`) —
the core #1383 behavior, working.
- **Fine-grained PAT**: without Members:read → personal namespace only
(fail-closed); after adding Members:read → the org (Owner) namespace is
granted. This is what the new docs describe.

No runtime behavior change here beyond the added test; the docs and
comment are the substance.

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-10 18:48:56 -04:00
..
administration Add registry maintainer onboarding documentation (#820) 2025-12-08 13:43:37 +00:00
contributing Fix broken reference documentation links (#1387) 2026-06-25 06:44:48 -04:00
design update schema url point to the actual location (#884) 2026-02-10 13:32:58 -08:00
modelcontextprotocol-io docs(auth): document fine-grained PAT permission for org publishing (+ pagination-cap test) (#1435) 2026-07-10 18:48:56 -04:00
reference Fix broken reference documentation links (#1387) 2026-06-25 06:44:48 -04:00
community-projects.md docs: add ToolHive Registry Server to community projects (#1261) 2026-05-07 10:36:03 -04:00
README.md docs: fix broken links in Documentation Index (#822) 2025-12-08 13:43:16 +00:00

README.md

MCP Registry Documentation

The MCP registry provides MCP clients with a list of MCP servers, like an app store for MCP servers.

I want to...

Documentation Index