Hlix MCP Servers API

openapi: 3.2.0
info:
  description: Explore the Hlix API for projects, agent teams, and delivery workflows. Authenticate with `x-api-key` and select a Workspace with `X-Organization-Id`. Session-only operations require a signed-in user session. Authentication setup.
  title: reference MCP Servers API
  version: 1.0.0
servers:
- url: https://server.hlix.ai
  description: API server
security:
- apiKey: []
- sessionCookie: []
tags:
- name: mcp-servers
paths:
  /v1/api/mcp-servers:
    get:
      operationId: listMcpServers
      parameters:
      - description: List only connections belonging to this project. Omitted lists workspace connections.
        in: query
        name: projectId
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/McpServer'
                type: array
          description: 'Every registered server, enabled or not. `env` values are write-only: each key is listed and every value reads as an empty string.'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
      summary: List MCP servers in workspace or project scope
      tags:
      - mcp-servers
    post:
      operationId: createMcpServer
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMcpServer'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServer'
          description: The stored row.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`).
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Writing the registry is owner/admin only. (Or the caller is not a member of this workspace at all.)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The server could not be written.
      summary: Register an MCP server
      tags:
      - mcp-servers
  /v1/api/mcp-servers/{id}:
    delete:
      operationId: deleteMcpServer
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageAck'
          description: The server is gone.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Writing the registry is owner/admin only. (Or the caller is not a member of this workspace at all.)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such MCP server in this workspace.
      summary: Delete an MCP server
      tags:
      - mcp-servers
    get:
      operationId: getMcpServer
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServer'
          description: The row.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such MCP server in this workspace.
      summary: Get one MCP server
      tags:
      - mcp-servers
    patch:
      operationId: updateMcpServer
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMcpServer'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServer'
          description: The updated row. An `env` value sent as an empty string keeps the stored value for that key.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`).
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Writing the registry is owner/admin only. (Or the caller is not a member of this workspace at all.)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such MCP server in this workspace.
      summary: Update an MCP server
      tags:
      - mcp-servers
  /v1/api/mcp-servers/{id}/connect:
    post:
      operationId: connectMcpServer
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpConnect'
          description: The provider authorization URL and safe connection status. Requires a signed-in browser session.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Writing the registry is owner/admin only. (Or the caller is not a member of this workspace at all.)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such MCP server in this workspace.
      security:
      - sessionCookie: []
      summary: Start hosted OAuth for a remote MCP connection
      tags:
      - mcp-servers
  /v1/api/mcp-servers/{id}/disconnect:
    post:
      operationId: disconnectMcpServer
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServer'
          description: The disconnected server. Its configuration remains saved.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Writing the registry is owner/admin only. (Or the caller is not a member of this workspace at all.)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such MCP server in this workspace.
      summary: Disconnect OAuth and invalidate discovered tools
      tags:
      - mcp-servers
  /v1/api/mcp-servers/{id}/discover:
    post:
      operationId: discoverMcpServer
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServer'
          description: The connection with its saved discovery status. No tool is executed.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Writing the registry is owner/admin only. (Or the caller is not a member of this workspace at all.)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such MCP server in this workspace.
      summary: Discover and save the remote server tool catalog
      tags:
      - mcp-servers
components:
  schemas:
    ApiError:
      additionalProperties: {}
      properties:
        error:
          type: string
      required:
      - error
      type: object
    UpdateMcpServer:
      properties:
        args:
          anyOf:
          - items:
              maxLength: 500
              type: string
            maxItems: 64
            type: array
          - type: 'null'
        authentication:
          enum:
          - headers
          - oauth
          type: string
        command:
          anyOf:
          - maxLength: 500
            type: string
          - type: 'null'
        description:
          anyOf:
          - maxLength: 2000
            type: string
          - type: 'null'
        enabled:
          type: boolean
        env:
          anyOf:
          - additionalProperties:
              maxLength: 10000
              type: string
            propertyNames:
              maxLength: 256
              minLength: 1
              type: string
            type: object
          - type: 'null'
        name:
          maxLength: 100
          minLength: 1
          type: string
        oauthClientId:
          anyOf:
          - maxLength: 2000
            type: string
          - type: 'null'
        oauthClientSecret:
          anyOf:
          - maxLength: 10000
            type: string
          - type: 'null'
        projectId:
          anyOf:
          - format: uuid
            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            type: string
          - type: 'null'
        transport:
          enum:
          - stdio
          - http
          - sse
          type: string
        url:
          anyOf:
          - anyOf:
            - format: uri
              maxLength: 4000
              type: string
            - const: ''
              type: string
          - type: 'null'
      type: object
    McpServer:
      properties:
        args:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
        authentication:
          enum:
          - headers
          - oauth
          type: string
        command:
          type:
          - string
          - 'null'
        connection:
          properties:
            checkedAt:
              type:
              - string
              - 'null'
            errorCode:
              anyOf:
              - enum:
                - public_https_required
                - connection_failed
                - authorization_required
                - oauth_client_required
                - unsupported_contract
                - catalog_too_large
                type: string
              - type: 'null'
            status:
              enum:
              - sandbox_only
              - not_checked
              - ready
              - authorization_required
              - disconnected
              - error
              - disabled
              type: string
            toolCount:
              maximum: 9007199254740991
              minimum: 0
              type: integer
          required:
          - status
          - toolCount
          - checkedAt
          - errorCode
          type: object
        createdAt:
          type: string
        description:
          type:
          - string
          - 'null'
        enabled:
          type: boolean
        env:
          anyOf:
          - additionalProperties:
              type: string
            propertyNames:
              type: string
            type: object
          - type: 'null'
        hasOauthClientSecret:
          type: boolean
        id:
          type: string
        name:
          type: string
        oauthClientId:
          type:
          - string
          - 'null'
        organizationId:
          type: string
        projectId:
          type:
          - string
          - 'null'
        transport:
          enum:
          - stdio
          - http
          - sse
          type: string
        updatedAt:
          type: string
        url:
          type:
          - string
          - 'null'
      required:
      - id
      - organizationId
      - projectId
      - name
      - description
      - transport
      - command
      - args
      - url
      - env
      - enabled
      - authentication
      - oauthClientId
      - hasOauthClientSecret
      - connection
      - createdAt
      - updatedAt
      type: object
    CreateMcpServer:
      properties:
        args:
          anyOf:
          - items:
              maxLength: 500
              type: string
            maxItems: 64
            type: array
          - type: 'null'
        authentication:
          enum:
          - headers
          - oauth
          type: string
        command:
          anyOf:
          - maxLength: 500
            type: string
          - type: 'null'
        description:
          anyOf:
          - maxLength: 2000
            type: string
          - type: 'null'
        enabled:
          type: boolean
        env:
          anyOf:
          - additionalProperties:
              maxLength: 10000
              type: string
            propertyNames:
              maxLength: 256
              minLength: 1
              type: string
            type: object
          - type: 'null'
        name:
          maxLength: 100
          minLength: 1
          type: string
        oauthClientId:
          anyOf:
          - maxLength: 2000
            type: string
          - type: 'null'
        oauthClientSecret:
          anyOf:
          - maxLength: 10000
            type: string
          - type: 'null'
        projectId:
          anyOf:
          - format: uuid
            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            type: string
          - type: 'null'
        transport:
          enum:
          - stdio
          - http
          - sse
          type: string
        url:
          anyOf:
          - anyOf:
            - format: uri
              maxLength: 4000
              type: string
            - const: ''
              type: string
          - type: 'null'
      required:
      - name
      - transport
      type: object
    MessageAck:
      properties:
        message:
          type: string
      required:
      - message
      type: object
    McpConnect:
      properties:
        authorizationUrl:
          type:
          - string
          - 'null'
        server:
          properties:
            args:
              anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            authentication:
              enum:
              - headers
              - oauth
              type: string
            command:
              type:
              - string
              - 'null'
            connection:
              properties:
                checkedAt:
                  type:
                  - string
                  - 'null'
                errorCode:
                  anyOf:
                  - enum:
                    - public_https_required
                    - connection_failed
                    - authorization_required
                    - oauth_client_required
                    - unsupported_contract
                    - catalog_too_large
                    type: string
                  - type: 'null'
                status:
                  enum:
                  - sandbox_only
                  - not_checked
                  - ready
                  - authorization_required
                  - disconnected
                  - error
                  - disabled
                  type: string
                toolCount:
                  maximum: 9007199254740991
                  minimum: 0
                  type: integer
              required:
              - status
              - toolCount
              - checkedAt
              - errorCode
              type: object
            createdAt:
              type: string
            description:
              type:
              - string
              - 'null'
            enabled:
              type: boolean
            env:
              anyOf:
              - additionalProperties:
                  type: string
                propertyNames:
                  type: string
                type: object
              - type: 'null'
            hasOauthClientSecret:
              type: boolean
            id:
              type: string
            name:
              type: string
            oauthClientId:
              type:
              - string
              - 'null'
            organizationId:
              type: string
            projectId:
              type:
              - string
              - 'null'
            transport:
              enum:
              - stdio
              - http
              - sse
              type: string
            updatedAt:
              type: string
            url:
              type:
              - string
              - 'null'
          required:
          - id
          - organizationId
          - projectId
          - name
          - description
          - transport
          - command
          - args
          - url
          - env
          - enabled
          - authentication
          - oauthClientId
          - hasOauthClientSecret
          - connection
          - createdAt
          - updatedAt
          type: object
      required:
      - authorizationUrl
      - server
      type: object
    ValidationError:
      properties:
        error:
          properties:
            message:
              type: string
            name:
              type: string
          required:
          - name
          - message
          type: object
        success:
          const: false
          type: boolean
      required:
      - success
      - error
      type: object
  parameters:
    OrganizationId:
      description: The workspace (organization) to act in. Omitted, the session's active organization is used.
      in: header
      name: X-Organization-Id
      required: false
      schema:
        type: string
      example: YOUR_WORKSPACE_ID
  securitySchemes:
    apiKey:
      description: An API key issued through `/v1/api/auth/api-key/*`. Browser clients can use their session cookie instead.
      in: header
      name: x-api-key
      type: apiKey
    sessionCookie:
      description: The complete session Cookie header issued by sign-in at the selected API host. Cookie names vary by hosting region and environment; preserve the issued name and value. Browsers send these HTTP-only cookies automatically. Session-only operations require this user session and do not accept an API key.
      in: header
      name: Cookie
      type: apiKey