bubblio-dev MCP API

openapi: 3.2.0
info:
  title: Bubblio Dev MCP API
  version: 1.0.0
  contact:
    email: bubblio@andresio.com
  description: 'Operations tagged mcp across 2 of this provider''s published API definitions: openapi.yaml, bubblio-dev-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.bubblio.dev
  description: Hosted production platform — the canonical host.
- url: https://andresomar95--bubblio-api-serve.modal.run
  description: The same deployment under its infrastructure name (the SDK's default BUBBLIO_API_URL).
tags:
- name: MCP
  description: 'The MCP endpoints. Minimal, hand-rolled, STATELESS Streamable-HTTP servers: POST one

    JSON-RPC 2.0 message per request, receive one `application/json` response (legal per

    the MCP spec — no SSE, no session ids). Tool failures come back as `isError` RESULTS

    the calling model can read; JSON-RPC `error` objects are reserved for malformed

    requests, unknown methods, and unknown tools. Supported methods: `initialize`,

    `ping`, `tools/list`, `tools/call`; notifications (no `id`) are acknowledged 202.'
paths:
  /agent/hub/mcp:
    get:
      tags:
      - MCP
      summary: 'Stateless-JSON truth: nothing to GET'
      operationId: getHubMcp
      responses:
        '405':
          description: This MCP endpoint is stateless JSON — POST your JSON-RPC messages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalmError'
    post:
      tags:
      - MCP
      summary: The hub MCP endpoint (JSON-RPC 2.0, one message per request)
      description: 'Same envelope as every per-door endpoint (64KB body cap, notifications → 202,

        protocol errors as JSON-RPC `error` on HTTP 200). Tool routing differs in exactly

        two ways: a sixth tool `find { query }` searches the live directory, and the five

        door tools take a `door` argument (handle or door id) resolved through the

        UNCHANGED per-door machinery — custody, approvals, mandates, payments, and rate

        buckets all scope to the resolved door, exactly as if the agent had knocked on the

        door''s own URL. The hub is routing, never a bypass, and holds no credential.'
      operationId: postHubMcp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
      responses:
        '200':
          description: JSON-RPC result — or a JSON-RPC error object for malformed/unknown requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '202':
          description: 'Notification (no `id`): acknowledged, no body.'
        '413':
          description: Body over 64KB (JSON-RPC error envelope).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '429':
          description: 'A published ceiling tripped (JSON-RPC error envelope, code -32000; HTTP 429 so

            generic clients back off too). `Retry-After` is advisory and clamped to 3600s;

            the MESSAGE carries the real limit to pace against.

            '
          headers:
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
    servers:
    - url: https://api.bubblio.dev
      description: Hosted production platform — the canonical host.
    - url: https://andresomar95--bubblio-api-serve.modal.run
      description: The same deployment under its infrastructure name (the SDK's default BUBBLIO_API_URL).
  /agent/{doorId}/mcp:
    get:
      tags:
      - MCP
      summary: 'Stateless-JSON truth: nothing to GET'
      operationId: getDoorMcp
      parameters:
      - $ref: '#/components/parameters/doorId'
      responses:
        '405':
          description: POST your JSON-RPC messages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalmError'
        '404':
          $ref: '#/components/responses/DoorMiss'
    post:
      tags:
      - MCP
      summary: A door's MCP endpoint (JSON-RPC 2.0, one message per request)
      description: 'Tools served: `about` and `ask` always; `list_actions`, `quote`, `confirm` only

        while the owner has ≥1 visible action. Tool-call RESULTS are MCP content — one

        `{ type: ''text'', text }` block whose text is a JSON document; the important shapes

        are catalogued under components (QuoteAnswer, ConfirmAnswer, Receipt).


        The action lifecycle, in one paragraph: `quote { tool, args, agent_key? }` pins

        exactly what would run (10-minute TTL; for priced actions the pin IS the price

        guarantee) and answers a `quote_id`. `confirm { quote_id, agent_key? }` executes it

        EXACTLY once — the quote is consumed by a winner-only conditional update, and a

        duplicate confirm replays the original receipt (marked `replayed: true`) instead of

        re-executing. A keyed quote is BOUND to the credential that quoted: confirm must

        re-present the same key, or the quote reads as nonexistent — a quote_id alone is

        never a bearer token. Quotes needing human approval answer `status: needs_approval`

        with a `relay_script` for the human and an approval link; `confirm` doubles as the

        NON-consuming poll (`wait_seconds` ≤ 25) answering `awaiting_human` /

        `awaiting_payment` until the decision or settlement lands.'
      operationId: postDoorMcp
      parameters:
      - $ref: '#/components/parameters/doorId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
      responses:
        '200':
          description: JSON-RPC result or protocol error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '202':
          description: 'Notification (no `id`): acknowledged, no body.'
        '404':
          $ref: '#/components/responses/DoorMiss'
        '413':
          description: Body over 64KB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '429':
          description: A published ceiling tripped (see the hub endpoint's note).
          headers:
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
    servers:
    - url: https://api.bubblio.dev
      description: Hosted production platform — the canonical host.
    - url: https://andresomar95--bubblio-api-serve.modal.run
      description: The same deployment under its infrastructure name (the SDK's default BUBBLIO_API_URL).
components:
  schemas:
    JsonRpcRequest:
      type: object
      required:
      - jsonrpc
      - method
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          type:
          - string
          - number
          - 'null'
          description: Omit entirely for a notification (answered 202, no body).
        method:
          type: string
          enum:
          - initialize
          - ping
          - tools/list
          - tools/call
        params:
          type: object
          description: 'For tools/call: { name, arguments }.'
    CalmError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        code:
          type: string
          description: Machine-readable refusal code, present where documented — branch on this, never on message text.
    JsonRpcResponse:
      type: object
      required:
      - jsonrpc
      - id
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          type:
          - string
          - number
          - 'null'
        result:
          type: object
          description: 'For tools/call: MCP content — `{ content: [{ type: ''text'', text }], isError? }`

            where `text` is a JSON document (see QuoteAnswer / ConfirmAnswer / Receipt for

            the action tools). Tool FAILURES arrive here with `isError: true`, phrased for

            the calling model; JSON-RPC `error` is reserved for protocol problems.

            '
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
    DoorId:
      type: string
      pattern: ^door_[a-f0-9]{12}$
  responses:
    DoorMiss:
      description: 'UNIFORM: unknown, malformed, disabled, unapproved, and migration-lagged doors all read the same.'
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                const: No agent door here.
  parameters:
    doorId:
      name: doorId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/DoorId'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: The platform's Bubblio API key (`bbl_…`). Server-side only.
    consentToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: The human's passkey-session token from `POST /approvals/session`.
x-refined-from:
- openapi.yaml
- bubblio-dev-openapi.yaml