Working With The Official MCP Server Registry API

Getting Started With the Official MCP Registry API

Posted in
J.Simpson

J Simpson
Bsky Icon
X Icon

The Model Context Protocol (MCP) community recently made quite a splash with the introduction of the Official MCP Registry, an open catalog of available MCP servers. This open-source directory is meant as a single point of discovery for all MCP servers, helping to make MCP servers more discoverable while enforcing a standardized format. It also allows developers to search for relevant MCP servers with a single REST API.

The introduction of the Official MCP Registry API promises to be as significant as the registry itself, as it creates a standard for structuring and describing MCP servers in the way that OpenAPI describes APIs. Not only will this standardization make it easier to find MCP servers, it will also help make them more secure. It will even be good for marketing MCP servers, as it will help developers get their tools and projects in front of the right audience.

The MCP server registry works with both public and private MCP servers, making it ideal for MCP discovery for internal as well as external resources. Considering how powerful and useful it is, we’ve put together a thorough walkthrough, giving you everything you need to know to go from an empty terminal to a fully-functional MCP discovery system.

The Anatomy of the Official MCP Registry API

Before we start showing you how you can use the Official MCP Registry API, let’s take a moment to consider the new OpenAPI specification for the MCP server registry. Knowing how MCP documents are structured will help you describe and publish your own MCPs, and will show you how to search for other MCP servers.

Here’s an excerpt from the MCP template published by the MCP community.

openapi: 3.1.0
jsonSchemaDialect: "https://json-schema.org/draft/2020-12/schema"
$id: https://modelcontextprotocol.io/schemas/draft/2025-09-29/server-registry-openapi
info:
  title: MCP Server Registry API
  version: "2025-09-29"
  summary: API for discovering and accessing MCP server metadata
  description: |
    Specification for a theoretical REST API that serves up metadata about MCP servers.
  license:
    name: MIT
    identifier: MIT

paths:
  /v0/servers:
    get:
      summary: List MCP servers
      description: Returns a list of all registered MCP servers
      parameters:
        - name: cursor
          in: query
          description: |
            Pagination cursor for retrieving next set of results.

            Cursors are opaque strings returned in the `metadata.nextCursor` field of paginated responses. Always use the exact cursor value returned by the API.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of items to return
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: A list of MCP servers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerList'

As you can see, the Official MCP Registry API is based upon the OpenAPI specification. This is good news for anybody already used to using APIs, as they’ll be able to transition to using the MCP server API with little trouble.

The first section of the description declares it was created using OpenAPI 3.1.0. It also tells the system which schema validation tool to use so that the syntax is correct. In this case, it’s https://json-schema.org/draft/2020-12/schema. Next, it gives the MCP server a unique identifier. Finally, the opening section gives the MCP server a title and shows when the version was corrected.

The next section describes how the MCP server is structured and how to use it. In this example, the /v0/servers endpoint uses the GET method to retrieve a list of all available servers. It also allows developers to describe any restrictions or special features the endpoint might possess. In this case, the /servers endpoint has a limit in place and uses cursor-based pagination, which keeps track of the position of a pointer to start the next page from the last seen document.

Finally, this excerpt details the responses returned by the endpoint. This server returns a 200 OK response when the request goes through successfully, and then returns a list of all available servers.

Calling the Official MCP Registry API

Now that we know how the OpenAPI document is structured, let’s begin working with the MCP Registry API.

1. Query the REST API

Let’s start by making your first API call. This will give you an idea of how the assets are formatted. Once you know how payloads are structured, you’ll be able to fine-tune your queries. To call the Official MCP Registry API, you’ll need both the root directory as well as the version you’re using. The root directory for the REST API is:

https://registry.modelcontextprotocol.io/

For this walkthrough, we’re using /v0. To retrieve a list of ten MCP servers from the registry API, we’d use the following call:

curl "https://registry.modelcontextprotocol.io/v0/servers?limit=10"

This will return a list of 10 MCP servers from the registry.

2. Search or Filter MCP Servers

Now that you’re able to make base calls, you’re ready to start refining your queries. Luckily, this is very easy to do with REST API calls. For example, if you wanted to return a list of MCP servers that use SQL, you’d configure your API call like this:

curl "https://registry.modelcontextprotocol.io/v0/servers?search=sql&limit=1"

This should return something similar to the following response:

{
  "servers": [
    {
      "server": {
        "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
        "name": "io.github.dba-i/mssql-dba",
        "description": "An MCP server that provides [describe what your server does]",
        "repository": {
          "url": "https://github.com/dba-i/mssql-dba",
          "source": "github"
        },
        "version": "1.0.0"
      },
      "_meta": {
        "io.modelcontextprotocol.registry/official": {
          "status": "active",
          "publishedAt": "2025-09-16T16:43:44.243434Z",
          "updatedAt": "2025-09-16T16:43:44.243434Z",
          "isLatest": true
        }
      }
    }
  ]
}

Before we move on, let’s take a moment to read through these results. Having a greater understanding of the assets returned by the Official MCP Registry API will let you work with the results with greater finesse.

To start, the name variable is simply the name of the MCP server using GitHub’s namespace style. Description describes what the MCP server does. In this example, the description has still been left blank. The repository field states where the MCP server is stored on GitHub. In this example, the server is stored at https://github.com/dba-i/mssql-dba. Version declares the current version of the MCP server — in this case, 1.0.0.

Finally, the results tell you how you can install the MCP server. For mssql-dba, you’ll use npm to install the server. Once it’s installed, the "type":"stdio" pairing shows that mssql-dba can be run from the command line. The "name":"YOUR_API_KEY" pairing shows that you’ll need to set the API key environment variable for this MCP server, if you haven’t already.

3. Fetch Full Metadata of a MCP Server

Now, let’s take a look at the complete data of a particular server. To start, we’re going to find a server we can query. We’re going to look up MCP servers that can interact with filesystems. Input the following command:

curl "https://registry.modelcontextprotocol.io/v0/servers?search=filesystem"

This should return a result like this (we’ve prettified the JSON formatting):

{
  "servers": [
    {
      "server": {
        "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
        "name": "io.github.bytedance/mcp-server-filesystem",
        "description": "MCP server for filesystem access",
        "repository": {
          "url": "https://github.com/bytedance/UI-TARS-desktop",
          "source": "github",
          "subfolder": "packages/agent-infra/mcp-servers/filesystem"
        },
        "version": "1.0.0",
        "packages": [
          {
            "registryType": "npm",
            "registryBaseUrl": "https://registry.npmjs.org",
            "identifier": "@agent-infra/mcp-server-filesystem",
            "version": "latest",
            "transport": {
              "type": "stdio"
            },
            "packageArguments": [
              {
                "description": "Comma-separated list of allowed directories for file operations",
                "isRequired": true,
                "format": "string",
                "type": "named",
                "name": "allowed-directories"
              }
            ]
          },
          {
            "registryType": "npm",
            "registryBaseUrl": "https://registry.npmjs.org",
            "identifier": "@agent-infra/mcp-server-filesystem",
            "version": "latest",
            "runtimeHint": "npx",
            "transport": {
              "type": "sse",
              "url": "http://127.0.0.1:{port}/sse"
            },
            "packageArguments": [
              {
                "description": "Comma-separated list of allowed directories for file operations",
                "isRequired": true,
                "format": "string",
                "type": "named",
                "name": "allowed-directories"
              },
              {
                "description": "Server port number",
                "isRequired": true,
                "format": "number",
                "default": "8089",
                "type": "named",
                "name": "port"
              }
            ]
          },
          {
            "registryType": "npm",
            "registryBaseUrl": "https://registry.npmjs.org",
            "identifier": "@agent-infra/mcp-server-filesystem",
            "version": "latest",
            "runtimeHint": "npx",
            "transport": {
              "type": "streamable-http",
              "url": "http://127.0.0.1:{port}/mcp"
            },
            "packageArguments": [
              {
                "description": "Comma-separated list of allowed directories for file operations",
                "isRequired": true,
                "format": "string",
                "type": "named",
                "name": "allowed-directories"
              },
              {
                "description": "Server port number",
                "isRequired": true,
                "format": "number",
                "default": "8089",
                "type": "named",
                "name": "port"
              }
            ]
          }
        ]
      },
      "_meta": {
        "io.modelcontextprotocol.registry/official": {
          "status": "active",
          "publishedAt": "2025-09-09T06:16:36.369748Z",
          "updatedAt": "2025-09-09T06:16:36.369748Z",
          "isLatest": true
        }
      }
    }
  ],
  "metadata": {
    "count": 1
  }
}

Once you’ve got all the metadata, it’s easy to filter the results however you like. For example, you can create a list of all of the servers that use a transport style of stdio, which stands for standardized output, meaning that the MCP server accepts inputs from a standard JSON file and then returns the output in a standardized format.

You could also create filters showing all of the MCP servers that are currently in their first version. This might serve as a useful shorthand for finding new MCP servers listed on the MCP registry. Best of all, you can do so without ever leaving the command prompt or your programming environment. The ability to filter and query the MCP Registry API means you can search for MCP servers that can interact with Slack, search the internet, add items to a Google calendar, automate tasks, and do a lot more.

Using the Official MCP Registry API from the command line is relatively simple, but it does require a bit of finesse. The API has a limit of 100 results per page, for example. To truly make the most of the MCP Server REST API, you should get comfortable with pagination and offsetting, if you’re not already. To help you get started, you can run a command like the following to retrieve all of the current MCP servers and merge them into a file called servers.json.

# Parameters
$limit = 100                   # Maximum servers per page (API limit)
$maxPages = 50                 # Safety limit to avoid runaway
$allServers = @()              # Array to hold all servers
$page = 0                      # Start page

# Loop through pages
while ($true) {
    $offset = $page * $limit
    $url = "https://registry.modelcontextprotocol.io/v0/servers?limit=$limit&offset=$offset"

    Write-Host "Fetching page $page (offset $offset)..."

    try {
        $response = curl $url
        $json = $response | ConvertFrom-Json
    } catch {
        Write-Warning "Failed to parse JSON. Stopping."
        break
    }

    # Stop if servers array is missing or empty
    if (-not $json.servers -or $json.servers.Count -eq 0) {
        Write-Host "No more servers returned. Stopping."
        break
    }

    # Add servers to array
    $allServers += $json.servers

    # Increment page
    $page++

    # Safety limit
    if ($page -ge $maxPages) {
        Write-Warning "Reached max pages ($maxPages). Stopping."
        break
    }
}

# Merge all servers into a single JSON object
$combined = @{ servers = $allServers } | ConvertTo-Json -Depth 10

# Save to file
$combined | Set-Content -Encoding UTF8 "C:\Users\jfore\Documents\Programming\Anniversaries\servers.json"

Write-Host "All servers saved to servers.json (total servers: $($allServers.Count))"

As you can see, it only requires fairly basic pagination and offsetting. Still, you’ll want to be at least somewhat comfortable coding to use the Official MCP Registry API from the command line.

4. How to Publish a MCP Server

Finally, we’ll wrap by showing you how you can publish your own MCP server.

Start by installing the Publisher CLI. If you’re on MacOS, they recommend installing Publisher using Homebrew. Input the following command:

brew install mcp-publisher

If you’re running Windows, you can install the Publisher CLI using PowerShell.

$arch = if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }; Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/download/v1.1.0/mcp-publisher_1.1.0_windows_$arch.tar.gz" -OutFile "mcp-publisher.tar.gz"; tar xf mcp-publisher.tar.gz mcp-publisher.exe; rm mcp-publisher.tar.gz
# Move mcp-publisher.exe to a directory in your PATH

Next, navigate to your MCP server’s directory and then use the Publisher CLI to create a template.

cd /path/to/your/mcp-server
mcp-publisher init

This should give you a generic servers.json file that looks something like this:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
  "name": "io.github.yourname/your-server",
  "description": "A description of your MCP server",
  "version": "1.0.0",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "your-package-name",
      "version": "1.0.0",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}

Once the template is generated, you can fill it out with your server’s particular details. You can also specify how your MCP server is installed, like npm or PyPi. Here’s an example of what that looks like for an NPM installer.

{
  "name": "your-npm-package",
  "version": "1.0.0",
  "mcpName": "io.github.username/server-name"
}

This field checks that the name detailed in the mcpName field matches the name of your MCP server. If it doesn’t, the installation fails.

Next, you’ll need to verify the authentication method for your MCP server if you’re planning on using one. If you’re using GitHub login for authentication, for example, you’d run the following code:

mcp-publisher login github

Now you’re ready to publish! Just use the following command:

mcp-publisher publish

That’s it! Your MCP server is now live and listed on the official MCP registry.

Final Thoughts on the MCP Registry REST API

The MCP Registry REST API isn’t just a new suite of developer tools. It’s also the programmatic gateway to a directory of verified MCP servers and a new standard, ensuring that new MCP servers will also be discoverable and secure. The API is especially useful for developers used to working with REST APIs, thanks to its similarity to the OpenAPI specification.

Whether you’re looking for existing MCP servers or you’re planning on publishing your own, the MCP Register REST API is a major stride in the right direction. It’s also a powerful asset for developers looking to make sure they’ve got the latest, most thorough selection of MCPs without having to manually update their tools.

The MCP Registry API could allow AI-driven IDEs like Claude to automatically implement MCP servers as plugins, for example. It also lets frameworks like LangChain or AutoGen auto-populate with the best MCPs for a task, using user intent. It could even enable a new category of commercial tools, helping new users and customers find the right MCP server. These are just a few of the extensive range of potential applications of this useful new technology.

J.

J Simpson

J. Simpson lives at the crossroads of logic and creativity. He writes and researches tech-related topics extensively for a wide variety of publications, including Forbes Finds. He is also a graphic designer, journalist, and academic writer, writing on the ways that technology is shaping our society while using the most cutting-edge tools and techniques to aid his path. He lives in Portland, Or.