hyreflow-ai MCP API

openapi: 3.2.0
info:
  title: hyreflow engine (local) MCP API
  version: 0.1.0
tags:
- name: MCP
paths:
  /api/v2/mcp/oauth/authorize:
    get:
      summary: Mcp Authorize Get
      operationId: mcp_authorize_get_api_v2_mcp_oauth_authorize_get
      parameters:
      - name: response_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Response Type
      - name: client_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Client Id
      - name: redirect_uri
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Redirect Uri
      - name: code_challenge
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Code Challenge
      - name: code_challenge_method
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Code Challenge Method
      - name: scope
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Scope
      - name: state
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: State
      - name: resource
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Resource
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - MCP
    post:
      summary: Mcp Authorize Post
      description: 'Consent approval. No CSRF token, and that rests on ONE property of the cookie rather than on an

        omission: identity here comes from `hf_session`, which is set `samesite="lax"` (see app.py), so a

        cross-site POST arrives without it and falls through to the 401 below. Client registration is open

        (RFC 7591), so an attacker can register their own redirect_uri — if that cookie is ever widened to

        `samesite=none`, this endpoint needs a real one-time token BEFORE that ships.'
      operationId: mcp_authorize_post_api_v2_mcp_oauth_authorize_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - MCP
  /api/v2/mcp/oauth/register:
    post:
      summary: Mcp Register
      operationId: mcp_register_api_v2_mcp_oauth_register_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - MCP
  /api/v2/mcp/oauth/token:
    post:
      summary: Mcp Token
      operationId: mcp_token_api_v2_mcp_oauth_token_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - MCP
  /api/v2/mcp/oauth/revoke:
    post:
      summary: Mcp Revoke
      operationId: mcp_revoke_api_v2_mcp_oauth_revoke_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - MCP
  /api/v2/mcp:
    get:
      summary: Mcp Get
      description: 'No server-initiated SSE streams: a GET without a valid bearer gets the discovery 401; with one,

        405 tells the client this server is single-response only.'
      operationId: mcp_get_api_v2_mcp_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - MCP
    post:
      summary: Mcp Post
      description: 'Streamable-HTTP transport, single-response mode: each JSON-RPC POST gets one application/json

        response (spec-compliant; SSE streams are optional and none of our responses benefit from them).

        Unauthenticated requests get the RFC 6750 401 that drives OAuth discovery in every compliant

        client.


        The body is read here and EVERYTHING else runs in a worker thread. The dispatch below calls the

        engine''s own sync route functions, which do blocking provider HTTP — a waterfall runs for tens of

        seconds. Awaiting that inline on the event loop stalls every other request in the process (one

        uvicorn worker serves the whole engine), including the container health check. Same discipline as

        `stripe_webhook`, the only other async route here.'
      operationId: mcp_post_api_v2_mcp_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - MCP
    delete:
      summary: Mcp Delete
      description: 'DELETE terminates an MCP SESSION, which is identified by `Mcp-Session-Id`. We never issue one —

        this server is stateless, every request stands alone — so there is nothing here to terminate, and the

        spec''s answer for a server without session termination is 405.


        It must NOT revoke the OAuth grant. Clients send DELETE as routine shutdown cleanup, and treating

        that as ''destroy my credentials'' would force a full re-authorization on every restart. Revocation is

        a deliberate act with its own endpoint: POST /api/v2/mcp/oauth/revoke (RFC 7009).'
      operationId: mcp_delete_api_v2_mcp_delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - MCP
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer