modelcontextprotocol/registry
Watch
1
0
Fork
You've already forked registry
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
registry/docs/reference/api/official-registry-api.md
Radoslav Dimitrov a25f166b4b
 docs: remove stale complete.md and fix remaining stale references (#1522) 
Deletes `complete.md` and cleans up the last references to the
pre-restructuring docs layout.

## Why `complete.md` goes

It is 2,944 lines (31% of all documentation lines in the repo)
self-described as *"all documentation from the docs/ directory compiled
into a single markdown file"*. But:

- **No generator exists.** No make target, no workflow, no script. `grep
-rn "complete\.md"` finds **zero** references anywhere in the repo.
- **It mirrors a docs tree that no longer exists** — `docs/guides/`,
`docs/explanations/`, `docs/concepts/`.
- **All 72 of its relative links are broken**, and six of the basenames
it references exist nowhere in the repo.
- **~14 current docs are missing from it entirely** (`about.mdx`,
`authentication.mdx`, `package-types.mdx`, both CHANGELOGs, ...).
- **Its `server.json` examples pin the superseded `2025-07-09` schema**
(current is `2025-12-11`).

The strongest argument is its own last commit. [PR
#1278](https://github.com/modelcontextprotocol/registry/pull/1278)
closed [issue
#767](https://github.com/modelcontextprotocol/registry/issues/767) — a
real user-reported CLI flag bug — by editing **only `complete.md`**. A
genuine fix landed in a file nobody reads, while the docs a reader would
actually find stayed wrong.

A generated file with no generator degrades into a trap: authoritative
enough that people edit it, with nothing validating it. If the
LLM-consumption use case is worth keeping, the right shape is a `make
docs-bundle` target plus a `check-docs-bundle` CI job mirroring the
existing `check-schema` pattern — happy to do that instead if you would
rather keep it.

## Remaining stale references

| File | Was | Now |
|---|---|---|
| `contributing/add-package-registry.md` | Add
`docs/guides/publishing/publish-[yourregistry].md`, update
`docs/guides/publishing/README.md` | Add a section to
`package-types.mdx`. These were the **last live references** to the
obsolete `docs/guides/` layout outside `complete.md` |
| `administration/maintainer-onboarding.md` | Add them to "Current key
maintainers" in README | "Registry Working Group" — the section that
actually exists |
| `reference/README.md` | Omitted 6 reference docs | Adds
`api/extensions.md`, `api/openapi.yaml`, `api/CHANGELOG.md`,
`server-json/CHANGELOG.md`, `server-json/CONTRIBUTING.md`,
`server-json/draft/` |
| `docs/README.md` | Index omitted `community-projects.md` | Listed |
| `reference/api/generic-registry-api.md` | `PUT .../versions/{version}`
"not implemented by official registry" | It **is** implemented
([edit.go:36](https://github.com/modelcontextprotocol/registry/blob/main/internal/api/handlers/v0/edit.go#L36)),
and `official-registry-api.md` already lists it as an admin endpoint |
| `reference/api/official-registry-api.md` | Omitted 3 registered routes
| Adds `POST /v0.1/validate` (which `mcp-publisher validate` calls),
`GET /v0.1/ping`, `GET /v0.1/version`, and notes these plus `/health`
are absent from `openapi.yaml` |
| `server-json/official-registry-requirements.md` | Per-registry
verification → `quickstart.mdx` | → `package-types.mdx`, which has an
Ownership Verification section per registry |
| `design/design-principles.md` | Sections 1,2,3,4,**6**,7 | Renumbered
1–6 |
| `contributing/releasing.md` | Steps 1,2,3,**5**,6 | Renumbered 1–5 |

I left the sibling `DELETE` claim in `generic-registry-api.md` alone —
it is accurate, no DELETE route is registered (the `http.MethodDelete`
hit in `server.go` is CORS config, not a route).

## Staleness banners rather than rewrites

**`design/tech-architecture.md`** is substantially fictional. Rather
than a vague "may be outdated", the banner lists what I verified is
wrong:

- Describes Helm-chart deployment; the registry is a plain `Deployment`
([registry.go:65](https://github.com/modelcontextprotocol/registry/blob/main/deploy/pkg/k8s/registry.go#L65)).
Helm is used only for third-party components.
- Diagram shows a `StatefulSet` on port **27017** — MongoDB's port. The
DB is PostgreSQL on 5432 via the CloudNativePG operator.
- Documents a `verify-domain` challenge flow (`POST /verify-domain`,
`/verify-domain/check`, server-issued tokens) that **was never built**.
- Documents `/admin/*` routes that are not registered.
- Says the DB stores user auth state and DNS verification records; only
`servers` and `server_extensions` tables exist.

**`design/roadmap.md`** still says "Phase 1: MVP/Go-Live (Current
Focus)" ~11 months after launch. I added a dated note rather than
inventing a current phase — that is a working-group call.

## Verification

All **101** remaining relative links across every `.md`/`.mdx` in the
repo resolve. The only two non-resolving matches are the intentional
`[project-name](link)` template placeholder and the moderation link
fixed in #1518.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 16:32:37 +03:00

5.5 KiB
Raw Blame History

Official MCP Registry API

This document describes the API for the official MCP Registry hosted at registry.modelcontextprotocol.io.

This API is based on the generic registry API with additional endpoints and authentication. For publishing servers using the API, see the publishing guide.

Base URLs

  • Production: https://registry.modelcontextprotocol.io
  • Staging: https://staging.registry.modelcontextprotocol.io

Interactive Documentation

Extensions

The official registry implements the Generic Registry API with the following specific configurations and extensions:

Authentication

Publishing requires namespace-based authentication:

  • GitHub OAuth - For io.github.* namespaces
  • GitHub OIDC - For publishing from GitHub Actions
  • DNS verification - For domain-based namespaces (com.example.*)
  • HTTP verification - For domain-based namespaces (com.example.*)

See Publisher Commands for authentication setup.

Package Validation

The official registry enforces additional package validation requirements when publishing.

Server List Filtering

The official registry extends the GET /v0.1/servers endpoint with additional query parameters for improved discovery and synchronization:

  • updated_since - Filter servers updated after RFC3339 timestamp (e.g., 2025-08-07T13:15:04.280Z)
  • search - Case-insensitive substring search on server names (e.g., filesystem)
    • This is intentionally simple. For more advanced searching and filtering, use a subregistry.
  • version - Filter by version (currently supports latest for latest versions only)
  • include_deleted - Include deleted servers in results (default: false, but automatically true when updated_since is provided for incremental sync)

These extensions enable efficient incremental synchronization for downstream registries and improved server discovery. Parameters can be combined and work with standard cursor-based pagination.

Example: GET /v0.1/servers?search=filesystem&updated_since=2025-08-01T00:00:00Z&version=latest

Server Detail

The GET /v0.1/servers/{serverName}/versions/{version} endpoint returns detailed information about a specific server version.

Path parameters:

  • serverName - URL-encoded server name (e.g., io.github.user%2Fmy-server)
  • version - Server version or latest for the most recent version

Query parameters:

  • include_deleted - Include deleted servers in results (default: false)

Server Version History

The GET /v0.1/servers/{serverName}/versions endpoint returns all versions of a server.

Path parameters:

  • serverName - URL-encoded server name (e.g., io.github.user%2Fmy-server)

Query parameters:

  • include_deleted - Include deleted servers in results (default: false)

Additional endpoints

Auth endpoints

  • POST /v0.1/auth/dns - Exchange signed DNS challenge for auth token
  • POST /v0.1/auth/http - Exchange signed HTTP challenge for auth token
  • POST /v0.1/auth/github-at - Exchange GitHub access token for auth token
  • POST /v0.1/auth/github-oidc - Exchange GitHub OIDC token for auth token
  • POST /v0.1/auth/oidc - Exchange Google OIDC token for auth token (for admins)

Status endpoints

Update Single Version Status

PATCH /v0.1/servers/{serverName}/versions/{version}/status - Update status of a specific server version.

Path parameters:

  • serverName - URL-encoded server name (e.g., io.github.user%2Fmy-server)
  • version - Server version to update

Request body:

  • status (required) - New status: active, deprecated, or deleted
  • statusMessage (optional) - Message explaining the status change (max 500 characters, not allowed when status is active)
Update All Versions Status

PATCH /v0.1/servers/{serverName}/status - Update status of all versions of a server in a single transaction.

Path parameters:

  • serverName - URL-encoded server name (e.g., io.github.user%2Fmy-server)

Request body:

  • status (required) - New status: active, deprecated, or deleted
  • statusMessage (optional) - Message explaining the status change (max 500 characters, not allowed when status is active)

Status values:

  • active - Server is active and visible in default listings
  • deprecated - Server is deprecated but still visible with a warning message
  • deleted - Server is hidden from default listings (use include_deleted=true to show)

Authentication: Requires publish or edit permission for the server namespace.

Validation endpoint

  • POST /v0.1/validate - Validate a server.json without publishing it. Used by mcp-publisher validate.

Service endpoints

  • GET /v0.1/ping - Liveness check
  • GET /v0.1/version - Registry version information

Admin endpoints

  • GET /metrics - Prometheus metrics endpoint
  • GET /v0.1/health - Basic health check endpoint
  • PUT /v0.1/servers/{serverName}/versions/{version} - Edit specific server version

Note that /v0.1/validate, /v0.1/ping, /v0.1/version and /v0.1/health are not described in openapi.yaml, which covers the server and publish endpoints only.