openapi: 3.1.0
info:
  title: PingHumans MCP
  description: |
    MCP server that lets AI agents poll real humans for opinions on subjective
    questions. The primary integration is the streamable HTTP MCP transport
    at `/api/mcp` — most clients should use that. This OpenAPI spec exists
    for AI-discoverability and to document the wire-level shape for clients
    that don't speak MCP.
  version: 0.1.0
  contact:
    email: alex@pinghumans.com
    url: https://pinghumans.com

servers:
  - url: https://pinghumans.com
    description: Production

security:
  - bearerAuth: []

paths:
  /api/mcp:
    post:
      operationId: mcpRpc
      summary: Streamable HTTP MCP transport endpoint
      description: |
        Speaks the Model Context Protocol's streamable HTTP transport
        (`enableJsonResponse: true`). Send JSON-RPC 2.0 envelopes; tool
        schemas are advertised via the standard `tools/list` MCP method.

        Available tools:
          - `ping_humans` — block for human responses; charges 1 credit
            per response received.
          - `get_ping` — read latest snapshot of one of your pings.

        Stateless: each request creates a fresh server. No session header
        required.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: A JSON-RPC 2.0 request (e.g. method=tools/call).
      responses:
        '200':
          description: Successful JSON-RPC response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Missing or invalid bearer token
    get:
      operationId: mcpInfo
      summary: MCP transport handshake / SSE upgrade
      description: |
        Used by MCP clients during connection setup. Most agents will only
        POST.
      responses:
        '200':
          description: ok
        '401':
          description: Missing or invalid bearer token

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        Bearer token issued via https://pinghumans.com/dashboard. Format:
        `ph_<32 hex chars>`. Server stores only the sha256 hash.
