AllMCPs Acp API

openapi: 3.2.0
info:
  title: AllMCPs Directory Acp 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: Acp
paths:
  /api/acp/checkout_sessions:
    post:
      summary: Agentic Commerce Protocol checkout (boosts)
      description: 'ACP 2026-04-17 checkout_sessions API for buying listing boosts with a Stripe shared payment token. Also GET/POST /api/acp/checkout_sessions/{id}, POST .../complete and .../cancel. Needs `Authorization: Bearer` (agent token with the checkout:write scope), `API-Version: 2026-04-17` and `Idempotency-Key`. Item ids are `:`; quantity is weeks for weekly SKUs. Full contract: https://github.com/agentic-commerce-protocol/agentic-commerce-protocol. Returns 503 while ACP is not enabled.'
      operationId: acpCreateCheckoutSession
      security:
      - agentBearerAuth:
        - checkout:write
      responses:
        '201':
          description: The checkout session.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad headers or line items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid agent token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: ACP is not enabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Acp
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.
  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).'