Watch

adam jones 2e7108d366

Big docs tidy up in preparation for launch (#364 )

## Motivation and Context
Docs currently don't have very clear organisation, and don't explain
core flows.

This fixes #89 (although we still might want to push these to
`https://modelcontextprotocol.io/docs/`), based on the plan there.

One minor change from that plan is that I merged tutorials and guides,
because they ended up basically being duplicates which I thought would
be annoying for us to keep in sync. Additionally in the Diátaxis
framework, tutorials and guides are separated by whether they are
focused on acquisition of skills (e.g. in a learning environment) or
application of skills (e.g. in a work environment). I expect the
registry to be something that will be used occasionally in a work
environment, rather than a fundamental 'learnable' skill so I think it's
reasonable not to have tutorials and fold these into guides.

## How Has This Been Tested?
- Read through all these updated docs
- Unit and integration tests (that previously used examples.md and use
the schema) working
- Ran `npx markdown-link-check .` to check all the links work

## Breaking Changes
Links to old docs will break, but I don't think there are any. All
internal links have been checked and updated.

## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update

2025-09-07 10:44:42 +01:00

3.7 KiB

Raw Blame History

Consuming Registry Data via REST API

Integration patterns and best practices for building applications that consume MCP registry data.

Key details

Base URL: https://registry.modelcontextprotocol.io

Authentication: Not required for read-only access

GET /v0/servers - List all servers with pagination
GET /v0/servers/{id} - Get full server details including packages and configuration

See the interactive API documentation for complete request/response schemas.

Disclaimer: The official registry provides no uptime or data durability guarantees. You should design your applications to handle service downtime via caching.

Building a subregistry

Create enhanced registries - ETL official registry data and add your own metadata like ratings, security scans, or compatibility info.

For now we recommend scraping the GET /v0/servers endpoint on some regular basis. In the future we might provide a filter for updated_at (#291) to get only recently changed servers.

Servers are generally immutable, except for the status field which can be updated to deleted (among other states). For these packages, we recommend you also update the status field to deleted or remove the package from your registry quickly. This is because this status generally indicates it has violated our permissive moderation guidelines, suggesting it is illegal, malware or spam.

Filtering & Enhancement

The official registry has a permissive moderation policy, so you may want to implement your own filtering on top of registry data.

You can also add custom metadata to servers using the _meta field. For example, user ratings, download counts, or security scan results. If you do this, we recommend you put this under a key that is namespaced to your organization, for example:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "io.github.yourname/weather-server",
  "description": "MCP server for weather data access",
  "status": "active",
  "version_detail": {
    "version": "1.0.0"
  },
  "packages": [
    {
      "registry_type": "npm",
      "identifier": "weather-mcp-server",
      "version": "1.0.0"
    }
  ],
  "_meta": {
    "com.example.subregistry/custom": {
    "user_rating": 4.5,
      "download_count": 12345,
      "security_scan": {
        "last_scanned": "2024-06-01T12:00:00Z",
        "vulnerabilities_found": 0
      }
    }
  }
}

Providing an API

We recommend that your subregistry provides an API meeting the registry API specification, so it's easy for clients to switch between registries. See the registry API documentation for details.

MCP Client Integration

Convert registry data to client configuration - Fetch servers and transform package information into your MCP client's config format.

We highly recommend using a subregistry rather than fetching data from the official registry directly. You might want to make this configurable so that users of your client can choose their preferred registry, for example we expect that some enterprise users may have their own registry.

Your client should gracefully handle registries that meet the minimum spec, i.e. avoid hard dependencies on _meta fields.

Filtering

You likely should filter out servers that are not active in the status field.

Running servers

You can use the packages or remotes field to determine how to run a server. More details of these fields are in the server.json documentation.

3.7 KiB Raw Blame History