{
  "openapi": "3.1.0",
  "info": {
    "title": "MCP Atlas Public API",
    "version": "1.0.0",
    "description": "Read-only public API for the MCP Atlas directory of Model Context Protocol servers. No authentication required. GET requests only. Rate limit: 60 requests per minute per client (best-effort, per edge isolate); exceeded limits return 429 with a Retry-After header. All responses support ETag/If-None-Match and Cache-Control. Data is aggregated from the official MCP Registry and other attributed sources; unknown values are null, never invented.",
    "contact": {
      "url": "https://zeroo.online/contact"
    }
  },
  "servers": [
    {
      "url": "https://zeroo.online"
    },
    {
      "url": "https://zeroo.online/api/public",
      "description": "Auth-free mirror prefix (use /api/public/v1/... paths)"
    }
  ],
  "paths": {
    "/api/v1/servers": {
      "get": {
        "summary": "List MCP servers",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "Full-text search over names and descriptions."
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Category id from /api/v1/categories."
          },
          {
            "name": "transport",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "stdio",
                "http"
              ]
            }
          },
          {
            "name": "hosting",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "self-hosted",
                "cloud"
              ]
            }
          },
          {
            "name": "verified",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "true"
              ]
            },
            "description": "Only servers active in the official MCP Registry."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "updated",
                "stars",
                "verified",
                "name"
              ],
              "default": "updated"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of servers.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string",
                            "description": "Canonical registry name (e.g. owner/repo)."
                          },
                          "title": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "description": {
                            "type": "string"
                          },
                          "version": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "url": {
                            "type": "string",
                            "description": "Canonical listing page on MCP Atlas."
                          },
                          "repository_url": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "website_url": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "categories": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "transports": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "ecosystems": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "packages": {
                            "type": "array",
                            "items": {
                              "type": "object"
                            }
                          },
                          "remotes": {
                            "type": "array",
                            "items": {
                              "type": "object"
                            }
                          },
                          "hosting": {
                            "type": "object",
                            "properties": {
                              "local_package": {
                                "type": "boolean"
                              },
                              "remote_endpoint": {
                                "type": "boolean"
                              }
                            }
                          },
                          "verified": {
                            "type": "boolean",
                            "description": "True when the server is 'active' in the official MCP Registry. Not a security review."
                          },
                          "registry_status": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "availability_status": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "first_party": {
                            "type": "boolean",
                            "description": "Published by the operator of MCP Atlas (AiWorkPay)."
                          },
                          "featured": {
                            "type": "boolean"
                          },
                          "publisher": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "github": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "description": "Live GitHub metadata when retrievable; null fields mean unknown, never invented.",
                            "properties": {
                              "stars": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "license": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "language": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "pushed_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "archived": {
                                "type": [
                                  "boolean",
                                  "null"
                                ]
                              },
                              "synced_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          },
                          "sources": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "IDs of data sources this listing was aggregated from."
                          },
                          "published_at": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "registry_updated_at": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "last_synced_at": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "total_pages": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/servers/{slug}": {
      "get": {
        "summary": "Get one server by slug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Server detail with provenance and publisher profile.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "slug": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string",
                          "description": "Canonical registry name (e.g. owner/repo)."
                        },
                        "title": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "description": {
                          "type": "string"
                        },
                        "version": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "url": {
                          "type": "string",
                          "description": "Canonical listing page on MCP Atlas."
                        },
                        "repository_url": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "website_url": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "categories": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "transports": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "ecosystems": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "packages": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "remotes": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "hosting": {
                          "type": "object",
                          "properties": {
                            "local_package": {
                              "type": "boolean"
                            },
                            "remote_endpoint": {
                              "type": "boolean"
                            }
                          }
                        },
                        "verified": {
                          "type": "boolean",
                          "description": "True when the server is 'active' in the official MCP Registry. Not a security review."
                        },
                        "registry_status": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "availability_status": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "first_party": {
                          "type": "boolean",
                          "description": "Published by the operator of MCP Atlas (AiWorkPay)."
                        },
                        "featured": {
                          "type": "boolean"
                        },
                        "publisher": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "github": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "description": "Live GitHub metadata when retrievable; null fields mean unknown, never invented.",
                          "properties": {
                            "stars": {
                              "type": [
                                "integer",
                                "null"
                              ]
                            },
                            "license": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "language": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "pushed_at": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "archived": {
                              "type": [
                                "boolean",
                                "null"
                              ]
                            },
                            "synced_at": {
                              "type": [
                                "string",
                                "null"
                              ]
                            }
                          }
                        },
                        "sources": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "IDs of data sources this listing was aggregated from."
                        },
                        "published_at": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "registry_updated_at": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "last_synced_at": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Server not found.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/categories": {
      "get": {
        "summary": "List categories with live server counts",
        "responses": {
          "200": {
            "description": "Category list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/sources": {
      "get": {
        "summary": "List data sources with ingestion mode and server counts",
        "responses": {
          "200": {
            "description": "Source list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "summary": "Search servers (requires q)",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated search results.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string",
                            "description": "Canonical registry name (e.g. owner/repo)."
                          },
                          "title": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "description": {
                            "type": "string"
                          },
                          "version": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "url": {
                            "type": "string",
                            "description": "Canonical listing page on MCP Atlas."
                          },
                          "repository_url": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "website_url": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "categories": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "transports": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "ecosystems": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "packages": {
                            "type": "array",
                            "items": {
                              "type": "object"
                            }
                          },
                          "remotes": {
                            "type": "array",
                            "items": {
                              "type": "object"
                            }
                          },
                          "hosting": {
                            "type": "object",
                            "properties": {
                              "local_package": {
                                "type": "boolean"
                              },
                              "remote_endpoint": {
                                "type": "boolean"
                              }
                            }
                          },
                          "verified": {
                            "type": "boolean",
                            "description": "True when the server is 'active' in the official MCP Registry. Not a security review."
                          },
                          "registry_status": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "availability_status": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "first_party": {
                            "type": "boolean",
                            "description": "Published by the operator of MCP Atlas (AiWorkPay)."
                          },
                          "featured": {
                            "type": "boolean"
                          },
                          "publisher": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "github": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "description": "Live GitHub metadata when retrievable; null fields mean unknown, never invented.",
                            "properties": {
                              "stars": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "license": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "language": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "pushed_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "archived": {
                                "type": [
                                  "boolean",
                                  "null"
                                ]
                              },
                              "synced_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          },
                          "sources": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "IDs of data sources this listing was aggregated from."
                          },
                          "published_at": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "registry_updated_at": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "last_synced_at": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "total_pages": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing q parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}