a25f166b4bDeletes `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>
125 lines
5.5 KiB
Markdown
125 lines
5.5 KiB
Markdown
# 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](./generic-registry-api.md) with additional endpoints and authentication. For publishing servers using the API, see the [publishing guide](../../modelcontextprotocol-io/quickstart.mdx).
|
|
|
|
## Base URLs
|
|
|
|
- **Production**: `https://registry.modelcontextprotocol.io`
|
|
- **Staging**: `https://staging.registry.modelcontextprotocol.io`
|
|
|
|
## Interactive Documentation
|
|
|
|
- **[Live API Docs](https://registry.modelcontextprotocol.io/docs)** - Stoplight elements with try-it-now functionality
|
|
- **[OpenAPI Spec](https://registry.modelcontextprotocol.io/openapi.yaml)** - Complete machine-readable specification
|
|
|
|
## Extensions
|
|
|
|
The official registry implements the [Generic Registry API](./generic-registry-api.md) 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](../cli/commands.md) for authentication setup.
|
|
|
|
### Package Validation
|
|
|
|
The official registry enforces additional [package validation requirements](../server-json/official-registry-requirements.md) 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](./openapi.yaml), which covers the server and publish endpoints only.
|