AllMCPs Search API

openapi: 3.2.0
info:
  title: AllMCPs Directory Search API
  description: 'Public API for querying and managing Model Context Protocol (MCP) servers listed on AllMCPs. Designed for AI agents, LLM tool callers, and developer integrations.


    **Versioning & deprecation policy**: this spec is URL-versioned (`/api/v1/...`). Endpoints are additive within v1 — existing fields are not removed or repurposed without a version bump. If an endpoint is ever deprecated, responses will carry a `Deprecation: true` header (and, once a removal date is set, a `Sunset: ` header) for at least 90 days before removal, and the change will be announced at https://allmcps.com/blog. There is currently no deprecated surface in v1.


    **Auth**: most endpoints are public/unauthenticated (see each operation). Listing-mutating agent actions require a scoped Bearer token — see `components.securitySchemes.agentBearerAuth` and https://allmcps.com/auth.md.'
  version: 1.0.0
  contact:
    name: AllMCPs Team
    url: https://allmcps.com/contact
    email: contact@allmcps.com
servers:
- url: https://allmcps.com
  description: Production Edge Server
tags:
- name: Search
paths:
  /api/v1/search:
    get:
      summary: Search and filter MCP servers
      description: Query active MCP servers by keyword or category with optional limit parameters. Public, unauthenticated.
      operationId: searchServers
      parameters:
      - name: q
        in: query
        description: Keyword search query
        required: false
        schema:
          type: string
      - name: category
        in: query
        description: Filter by category. Accepts the full stored name, the plain label, or the slug from /api/v1/categories — matching is case-insensitive and ignores surrounding whitespace, so "🗄️ Databases", "Databases", and "databases" are equivalent. An unrecognized value returns 400 unknown_category rather than an empty result set.
        required: false
        schema:
          type: string
        examples:
          slug:
            value: databases
            summary: Category slug
          label:
            value: Databases
            summary: Plain label
          name:
            value: 🗄️ Databases
            summary: Full stored name
      - name: limit
        in: query
        description: Maximum results to return (1-100)
        required: false
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 100
      - name: transport
        in: query
        description: 'Only servers installed over this transport: `stdio` (local process) or `remote` (hosted HTTP endpoint)'
        required: false
        schema:
          type: string
          enum:
          - stdio
          - remote
      - name: verified
        in: query
        description: '`1` = only servers AllMCPs has seen run: a live tools/list, a sandbox start that asked for keys, or a healthy remote endpoint'
        required: false
        schema:
          type: string
          enum:
          - '1'
      responses:
        '200':
          description: Successful search results
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
            RateLimit-Limit:
              schema:
                type: integer
              description: Requests allowed per window (see rate-limit docs at /docs/api).
            RateLimit-Remaining:
              schema:
                type: integer
              description: Requests remaining in the current window.
            RateLimit-Reset:
              schema:
                type: integer
              description: Seconds until the window resets.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  query:
                    type:
                    - string
                    - 'null'
                  category:
                    type:
                    - string
                    - 'null'
                    description: The canonical category the request resolved to (the exact stored name), or null when no category filter was applied.
                  servers:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        description:
                          type: string
                        category:
                          type: string
                        url:
                          type: string
                        isOfficial:
                          type: boolean
                          description: Published by the company behind the product (or a modelcontextprotocol reference server when officialSource is "reference"). Set by AllMCPs admins with evidence, never by payment.
                        officialSource:
                          type:
                          - string
                          - 'null'
                          enum:
                          - github-org
                          - vendor-endpoint
                          - registry-namespace
                          - vendor-docs
                          - reference
                          - null
                        ownerVerified:
                          type: boolean
                          description: The listing owner proved control of it (approved ownership claim).
                        isVerifiedActive:
                          type: boolean
                        upvotes:
                          type: integer
                        installName:
                          type: string
                        detailUrl:
                          type: string
                        markdownUrl:
                          type: string
        '400':
          description: Unknown category (error code "unknown_category"). Fetch /api/v1/categories for the accepted names, labels, and slugs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error while querying the catalog.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Search
components:
  schemas:
    Error:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
          description: Machine-readable error code, e.g. "not_found", "unauthorized", "insufficient_scope", "invalid_scope".
        message:
          type: string
          description: Human-readable explanation suitable for surfacing to a user or logging.
        details:
          type: array
          items: {}
          description: Optional field-level validation issues (present on 400 responses to malformed request bodies).
        status:
          type: integer
          description: Optional echo of the HTTP status code.
        docs:
          type: string
          format: uri
          description: Optional link to the relevant documentation for resolving this error.
  headers:
    Deprecation:
      description: RFC 8594 style. Present (value "true") only once this specific operation is deprecated; absent otherwise. Not present on any current v1 operation.
      schema:
        type: string
        enum:
        - 'true'
    Sunset:
      description: RFC 8594 style. Present only once a removal date has been set for a deprecated operation, at least 90 days out. Absent otherwise.
      schema:
        type: string
        format: date-time
  securitySchemes:
    agentBearerAuth:
      type: oauth2
      description: 'Bearer token minted via POST /api/v1/agent/register + /api/v1/agent/register/confirm (email-verified, no OAuth redirect flow). Send as `Authorization: Bearer amcp_...`. Also documented at /.well-known/oauth-protected-resource and /auth.md.'
      flows:
        clientCredentials:
          tokenUrl: https://allmcps.com/api/v1/agent/register/confirm
          scopes:
            listings:claim: 'Claim ownership of an existing MCP server listing via DNS TXT record, site verification badge, or GitHub README badge proof. Grants no other write access. Required by: POST /api/v1/agent/claim, MCP tool: verify_mcp_claim (with an agentToken).'
            checkout:write: 'Create, update, complete and cancel Agentic Commerce Protocol checkout sessions to buy listing boosts. Payment still needs a Stripe shared payment token the buyer granted; this scope alone cannot spend money. Required by: ACP: /api/acp/checkout_sessions (all endpoints).'