RFC: Public API spec for official MCP server registry

[tadasant]

Inline comments on details being worked here: #3

Pre-submission Checklist

• I have verified that this discussion would not be more appropriate as an issue in a specific repository
• I have searched existing discussions to avoid duplicates

Discussion Topic

A working group of MCP community members are working towards building the "official MCP server registry". The initial deliverable we are sprinting towards is a REST API that centralizes metadata about MCP servers by leaning on server creators to submit and maintain metadata about their servers in a standardized format.

We envision that MCP client applications and other "server aggregator" type consumers will be able to leverage this metadata in order to power functions like "extensions", "MCP marketplaces", and other UX that involves discovering and installing MCP servers.

An official UI experience will likely come as a next-step after the initial API launch.

Big thank you to everyone who has contributed input on this working group so far: @alexhancock, @dsp-ant, @jspahrsummers, Marc-Antoine Belanger, Benjamin Eckel, Chris Dickinson, @macoughl, @ravinahp, @jerome3o-anthropic, Topher Bullock, Henry Mao

This RFC is the first of several we expect to solicit feedback on before starting to push code. We'd love input to make sure what we're building appropriately serves the MCP community at large.

The scope here: what is the public-facing API we wish to expose to server metadata consumers? The rest of this post is a first pass at this - open to any sort of commentary. As we feel aligned on the high level goals, we can move it into a PR where we iron out the line by line details.

Goals

• Align on who the “consumers” of this API will be
• Align on what use cases the consumers should hope to achieve with access to this data
• Enumerate the REST endpoints used to serve this purpose
• Enumerate the data each endpoint would need to surface for an initial release

Non-Goals

• Exploration of the publisher side of the registry. While we should keep the data enumerations scoped to information the publisher could conceivably provide, discussion regarding how that data should get from the publisher to the registry is out of scope.

Considerations

• Avoid trapdoor requirements if we do not have clarity on their purpose and how they fit into MCP
• Offer some baseline level of security assurance and/or appropriate qualifications as to the lack of security guarantees on a per-server basis
• Pave a path to analogous private implementations of registries meshing well with this public API specification (e.g. keep spec flexible to point to non-public references)

Terminology

Transport Type is one of: Streamable, SSE, WebSockets, stdio, or any other custom transports over which MCP can be facilitated between client and server. Although “Streamable” involves an SSE connection in its lifecycle, we refer to Streamable (landed in the spec on 2025-03-26) as distinct from purely SSE, which was deprecated in that same revision. Read more here.

A Remote is an HTTP service representing an MCP server, accessible at some URL. An MCP client should be able to HTTP POST to this URL in order to kick off the Initialization step of the MCP lifecycle. A Remote should have exactly one Transport Type. If a Remote supports multiple Transport Types, we represent those as two distinct Remotes. Only multi-tenant enabled remotes would be listed here.

Use Cases & Consumers

MCP client applications should be able to leverage data obtained through this API to facilitate a “one click (or zero-click) install” experience within their user interfaces. This should be possible for both stdio-focused clients and web-focused clients.

Server aggregators facilitating various intermediate value props (e.g. hosting stdio servers as remotes; curation of quality servers) should be able to lean on this data without scraping the internet to discover new servers.

End-users of MCP should be able to leverage data obtained through this API to discover what MCP servers already exist that they may want to leverage within their usage of MCP client apps.

Endpoints

In general, we discourage direct usage of this API by user-powered actions. If you are the creator of an MCP client, we recommend you run a daily poll of this server metadata and maintain your own augmented copy to distribute to your users. This helps us keep scale for the centralized repository manageable.

This API will be defined as an OpenAPI schema.

GET /v1/servers

Request

Parameters	Type	Description	Default
limit	int	Number of results per page (maximum: 5000).	5000
offset	int	Number of results to skip for pagination.	0

Response

Key	Type	Description
servers	Server[]
next	string
total	int	Total number of results across all pages

Server

Key	Type	Description
id	UUID	Unique ID
name	string
description	string	Alphanumeric chars only (e.g. no URLs)
repository	Repository	Required (for now) even for remote-only servers as the source of truth for metadata.
version	string	Dynamically pulled from registry_canonical reference.

Response (example)

{
  "servers": [
    {
      "id": "a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1",
      "name": "@modelcontextprotocol/servers/src/filesystem",
      "description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
      "repository": {
        "url": "https://github.com/modelcontextprotocol/servers",
        "subfolder": "src/filesystem",
        "branch": "main",
        "commit": "d94b5f7ec7c6d7602c78a5e9b8a5b8c94d093eda"
      }
    }
  ],
  "next": "https://registry.modelcontextprotocol.io/servers?offset=50",
  "total_count": 1
}

GET /v1/servers/:id

Request

Parameters	Type	Description	Default
version	string	Desired packaged version (as logged by the canonical registry).	(latest)

Response

Key	Type	Description
id	UUID
name	string
description	string	Alphanumeric chars only (e.g. no URLs)
repository	Repository
version	string	Dynamically pulled from registry_canonical reference.
registry_canonical	Enum	One designated registry where this package is published that is to be considered canonical (but publishing on others e.g. Docker Hub is OK)
registries	Registry[]
remotes	Remote[]

Registry

Key	Type	Description
name	Enum
package_name	string
license	Enum
command_arguments	CommandArguments
environment_variables	EnvironmentVariable[]

Remote

Key	Type	Description
transport_type	Enum	e.g. streamable, sse, ws
url	string	To kick off initialization

CommandArguments

Key	Type	Description
subcommands	Subcommand[]
positional_arguments	PositionalArgument[]
named_arguments	NamedArgument[]

Subcommand

Key	Type	Description
name	string
description	string
subcommands	Subcommand[]
positional_arguments	PositionArgument[]
named_arguments	NamedArgument[]
is_required	boolean

Argument

Key	Value	Description
name	string
description	string
is_required	boolean
is_repeatable	boolean
is_editable	boolean
choices	string[]
default_value	string

PositionalArgument

Key	Type	Description
position	int
…Argument

NamedArgument

Key	Type	Description
short_flag	string
long_flag	string
requires_value	boolean
…Argument

EnvironmentVariable

Key	Type	Description
name	string
description	string
required	boolean

Response (Example)

{
  "id": "a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1",
  "name": "@modelcontextprotocol/servers/src/filesystem",
  "description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
  "version": "0.0.3",
  "repository": {
    "url": "https://github.com/modelcontextprotocol/servers",
    "subfolder": "src/filesystem",
    "branch": "main",
    "commit": "d94b5f7ec7c6d7602c78a5e9b8a5b8c94d093eda"
  },
  "registry_canonical": "npm",
  "registries": [
    {
      "name": "docker",
      "package_name": "mcp/filesystem",
      "license": "MIT",
      "command_arguments": {
        "subcommands": [
          {
            "name": "run",
            "description": "Run the Docker container",
            "is_required": true,
            "subcommands": [],
            "positional_arguments": [],
            "named_arguments": [
              {
                "short_flag": "-i", 
                "requires_value": false, 
                "is_required": true,
                "is_editable": false,
                "description": "Run in interactive mode"
              },
              {
                "long_flag": "--rm", 
                "requires_value": false, 
                "is_required": true,
                "is_editable": false,
                "description": "Remove container when it exits"
              },
              {
                "long_flag": "--mount", 
                "requires_value": true, 
                "is_required": true,
                "is_repeatable": true,
                "is_editable": true,
                "description": "Mount a volume into the container",
                "default_value": "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
                "choices": []
              }
            ]
          }
        ],
        "positional_arguments": [
          {
            "position": 0, 
            "name": "image", 
            "description": "Docker image name", 
            "default_value": "mcp/filesystem", 
            "is_required": true,
            "is_editable": false,
            "is_repeatable": false,
            "choices": []
          },
          {
            "position": 1, 
            "name": "root_path", 
            "description": "Root path for filesystem access", 
            "default_value": "/projects", 
            "is_required": true,
            "is_editable": false,
            "is_repeatable": false,
            "choices": []
          }
        ],
        "named_arguments": []
      },
      "environment_variables": [
        {
          "name": "LOG_LEVEL",
          "description": "Logging level (debug, info, warn, error)",
          "required": false
        }
      ]
    },
    {
      "name": "npm",
      "package_name": "@modelcontextprotocol/server-filesystem",
      "license": "MIT",
      "command_arguments": {
        "subcommands": [],
        "positional_arguments": [
          {
            "position": 0, 
            "name": "package", 
            "description": "NPM package name", 
            "default_value": "@modelcontextprotocol/server-filesystem", 
            "is_required": true,
            "is_editable": false,
            "is_repeatable": false,
            "choices": []
          },
          {
            "position": 1, 
            "name": "path", 
            "description": "Path to access", 
            "default_value": "/Users/username/Desktop", 
            "is_required": true,
            "is_editable": true,
            "is_repeatable": true,
            "choices": []
          }
        ],
        "named_arguments": [
          {
            "short_flag": "-y", 
            "requires_value": false, 
            "is_required": false, 
            "is_editable": false,
            "description": "Skip prompts and automatically answer yes",
            "choices": []
          }
        ]
      },
      "environment_variables": [
        {
          "name": "LOG_LEVEL",
          "description": "Logging level (debug, info, warn, error)",
          "required": false
        }
      ]
    }
  ],
  "remotes": [
    {
      "transport_type": "sse",
      "url": "https://mcp-fs.example.com/sse"
    }
  ]
}

Notes

• The rough idea here downstream of this API spec (to be discussed in more detail in later RFC’s) is that we would define an mcp.json schema that server creators would be able to “submit” to the official registry via a new CLI tool. Submissions would require pre-publication on GitHub (so as to piggyback GitHub’s auth, namespacing for an initial release).
• Name of server is kept unique by requiring usage of GitHub to publish mcp.json file
• A new version of metadata is published by explicit action by the server creator (i.e. we will not necessarily have an “mcp server version” bump every time a package is updated, unless the creator also explicitly bumps the mcp server version).
• The information in registry_canonical is used to maintain the concept of “version”
• Registry package name uniqueness is not enforced (we do not authenticate against npm, pypi, etc). This means it is possible for someone to either duplicate MCP server entries with different metadata, or introduce a package that is not actually an MCP server. We rely on the underlying registries to avoid facilitating exposure to unsafe code.

[tadasant]

Closing this in favor of:

• Development of the Official MCP Metaregistry #11 -- high level decisions
• OpenAPI spec for official registry API #3 -- OpenAPI spec