openapi: 3.1.0
info:
  title: Glif MCP API
  version: 1.0.0
  description: |-
    Glif's media-generation agent over the Model Context Protocol (MCP).

    The single endpoint `POST /api/mcp` speaks JSON-RPC 2.0 over Streamable
    HTTP (stateless; responses may stream as SSE). Authenticate with a
    bearer token — either a `glif_v1_…` API key or an MCP OAuth access token.

    Standard MCP methods are supported: `initialize`, `tools/list`,
    `tools/call`, and the tasks family (`tasks/get`, `tasks/result`,
    `tasks/cancel`, `tasks/list`) for long-running generations. Call
    `tools/list` for authoritative, machine-readable tool input/output
    schemas.

    Tools:
    - compose_project — create or continue a durable Glif project from a natural-language prompt; returns text + media resource links. Async-capable via MCP tasks.
    - get_project — read project state, recent messages, and generated media.
    - list_projects — list the authenticated user's recent projects.
    - list_user_skills — list the user's own saved Glif skills.
    - get_user_skill — fetch one of the user's own skills (instructions included).
    - upload_file — upload an image/video/audio and get a CDN URL (always available).
    - whoami — authenticated identity, plan, credit balance, recent spend (always available).
servers:
  - url: https://glif.app
    description: Production
security:
  - bearerAuth: []
paths:
  /api/mcp:
    post:
      summary: MCP JSON-RPC endpoint
      description: Send a JSON-RPC 2.0 request. See the MCP spec (https://modelcontextprotocol.io) for the envelope; call `tools/list` for the live tool schemas.
      operationId: mcpJsonRpc
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JsonRpcRequest"
            examples:
              toolsList:
                summary: List available tools
                value:
                  jsonrpc: "2.0"
                  id: 1
                  method: tools/list
              composeProject:
                summary: Call compose_project
                value:
                  jsonrpc: "2.0"
                  id: 2
                  method: tools/call
                  params:
                    name: compose_project
                    arguments:
                      prompt: a watercolor fox in a snowy forest
      responses:
        "200":
          description: JSON-RPC response (JSON, or SSE stream for streaming results).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonRpcResponse"
        "401":
          description: Missing or invalid bearer token.
        "429":
          description: Per-credential rate limit exceeded.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A `glif_v1_…` API key or an MCP OAuth access token.
  schemas:
    JsonRpcRequest:
      type: object
      required:
        - jsonrpc
        - method
      properties:
        jsonrpc:
          type: string
          const: "2.0"
        id:
          type:
            - string
            - number
        method:
          type: string
          examples:
            - tools/list
            - tools/call
        params:
          type: object
    JsonRpcResponse:
      type: object
      required:
        - jsonrpc
      properties:
        jsonrpc:
          type: string
          const: "2.0"
        id:
          type:
            - string
            - number
            - "null"
        result:
          type: object
        error:
          type: object
          properties:
            code:
              type: number
            message:
              type: string
