openapi: 3.2.0
info:
  title: HasMCP Manager Servers API
  version: 1.0.0
  description: API for managing HasMCP components like Variables, Providers, MCP Servers, Resources, and Prompts.
security:
- bearerAuth: []
tags:
- name: Servers
paths:
  /servers:
    get:
      summary: List MCP Servers
      operationId: listServers
      security:
      - oauth2:
        - server:list
      responses:
        '200':
          description: A list of MCP servers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListServersResponse'
      tags:
      - Servers
    post:
      summary: Create MCP Server
      operationId: createServer
      security:
      - oauth2:
        - server:create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServerRequest'
      responses:
        '201':
          description: MCP Server created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateServerResponse'
      tags:
      - Servers
  /servers/import:
    post:
      summary: Import MCP Server
      operationId: importServer
      security:
      - oauth2:
        - server:update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: ExportServer JSON schema spec
      responses:
        '201':
          description: MCP Server imported successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetServerResponse'
      tags:
      - Servers
  /servers/{id}:
    get:
      summary: Get MCP Server
      operationId: getServer
      security:
      - oauth2:
        - server:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: MCP Server ID
      responses:
        '200':
          description: MCP Server details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetServerResponse'
      tags:
      - Servers
    patch:
      summary: Update MCP Server
      operationId: updateServer
      security:
      - oauth2:
        - server:update
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: MCP Server ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateServerRequest'
      responses:
        '200':
          description: MCP Server updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateServerResponse'
      tags:
      - Servers
    delete:
      summary: Delete MCP Server
      operationId: deleteServer
      security:
      - oauth2:
        - server:delete
      parameters:
      - name: id
        in: path
        required: true
        description: MCP Server ID
        schema:
          type: string
          description: Git Connection ID
      responses:
        '204':
          description: MCP Server deleted
      tags:
      - Servers
  /servers/{id}/export:
    get:
      summary: Export MCP Server
      operationId: exportServer
      security:
      - oauth2:
        - server:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: MCP Server ID
      responses:
        '200':
          description: MCP Server exported successfully
          content:
            application/json:
              schema:
                type: object
                description: ExportServer JSON schema spec
      tags:
      - Servers
  /servers/{id}/tokens:
    post:
      summary: Create MCP Server Token
      operationId: createServerToken
      security:
      - oauth2:
        - server:create_token
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: MCP Server ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServerTokenRequest'
      responses:
        '201':
          description: MCP Server Token created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateServerTokenResponse'
      tags:
      - Servers
  /servers/{id}/tools:
    get:
      summary: List MCP Server Tools
      operationId: listServerTools
      security:
      - oauth2:
        - server:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: MCP Server ID
      responses:
        '200':
          description: A list of associated tools
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListServerToolsResponse'
      tags:
      - Servers
    post:
      summary: Create MCP Server Tool Association
      operationId: createServerTool
      security:
      - oauth2:
        - server:update
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: MCP Server ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServerToolRequest'
      responses:
        '201':
          description: Tool associated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateServerToolResponse'
      tags:
      - Servers
  /servers/{id}/tools/{toolID}:
    delete:
      summary: Delete MCP Server Tool Association
      operationId: deleteServerTool
      security:
      - oauth2:
        - server:update
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: MCP Server ID
      - name: toolID
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Tool association deleted
      tags:
      - Servers
  /servers/{id}/resources:
    get:
      summary: List MCP Server Resource Associations
      operationId: listServerResources
      security:
      - oauth2:
        - server:list
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: MCP Server ID
      responses:
        '200':
          description: A list of associated resources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListServerResourcesResponse'
      tags:
      - Servers
    post:
      summary: Create MCP Server Resource Association
      operationId: createServerResource
      security:
      - oauth2:
        - server:update
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: MCP Server ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServerResourceRequest'
      responses:
        '201':
          description: Resource associated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateServerResourceResponse'
      tags:
      - Servers
  /servers/{id}/resources/{resourceID}:
    delete:
      summary: Delete MCP Server Resource Association
      operationId: deleteServerResource
      security:
      - oauth2:
        - server:update
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: MCP Server ID
      - name: resourceID
        in: path
        required: true
        schema:
          type: string
          description: Resource ID to disassociate
      responses:
        '204':
          description: Resource association deleted
      tags:
      - Servers
  /servers/{id}/prompts:
    get:
      summary: List MCP Server Prompt Associations
      operationId: listServerPrompts
      security:
      - oauth2:
        - server:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: MCP Server ID
      responses:
        '200':
          description: A list of associated prompts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListServerPromptsResponse'
      tags:
      - Servers
    post:
      summary: Create MCP Server Prompt Association
      operationId: createServerPrompt
      security:
      - oauth2:
        - server:update
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: MCP Server ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServerPromptRequest'
      responses:
        '201':
          description: Prompt associated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateServerPromptResponse'
      tags:
      - Servers
  /servers/{id}/prompts/{promptID}:
    delete:
      summary: Delete MCP Server Prompt Association
      operationId: deleteServerPrompt
      security:
      - oauth2:
        - server:update
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: MCP Server ID
      - name: promptID
        in: path
        required: true
        schema:
          type: string
          description: Prompt ID to disassociate
      responses:
        '204':
          description: Prompt association deleted
      tags:
      - Servers
components:
  schemas:
    ListServerResourcesResponse:
      type: object
      properties:
        resources:
          type: array
          items:
            $ref: '#/components/schemas/ServerResource'
    ProviderResource:
      type: object
      properties:
        id:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        name:
          type: string
        description:
          type: string
        uri:
          type: string
          format: uri
        mimeType:
          type: string
          example: text/plain
        size:
          type: integer
          format: int64
        annotations:
          type: object
          description: A raw JSON message for annotations.
          additionalProperties: true
    ServerCreate:
      type: object
      properties:
        name:
          type: string
        instructions:
          type: string
        version:
          type: integer
          format: int32
        providers:
          type: array
          description: Array of providers to associate, only ID and nested Tool IDs are used.
          items:
            type: object
            properties:
              id:
                type: string
                pattern: ^[A-Za-z0-9]{11}$
                example: kSuB9Gf6aD4
              tools:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      pattern: ^[A-Za-z0-9]{11}$
                      example: kSuB9Gf6aD4
        resources:
          type: array
          description: Array of resources to associate, only ID is used.
          items:
            type: object
            properties:
              id:
                type: string
                pattern: ^[A-Za-z0-9]{11}$
                example: kSuB9Gf6aD4
        prompts:
          type: array
          description: Array of prompts to associate, only ID is used.
          items:
            type: object
            properties:
              id:
                type: string
                pattern: ^[A-Za-z0-9]{11}$
                example: kSuB9Gf6aD4
    ServerTokenCreate:
      type: object
      properties:
        expiresAt:
          type: string
          format: date-time
        name:
          type: string
    CreateServerTokenResponse:
      type: object
      properties:
        token:
          $ref: '#/components/schemas/ServerToken'
    Server:
      type: object
      properties:
        id:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        name:
          type: string
        description:
          type: string
        requestHeadersProxyEnabled:
          type: boolean
        dynamicToolDiscoveryEnabled:
          type: boolean
        version:
          type: integer
          format: int32
        gitProvider:
          type: string
        gitRepoFullName:
          type: string
        providers:
          type: array
          items:
            $ref: '#/components/schemas/Provider'
        resources:
          type: array
          items:
            $ref: '#/components/schemas/ProviderResource'
        prompts:
          type: array
          items:
            $ref: '#/components/schemas/ProviderPrompt'
    ProviderOAuth2Config:
      type: object
      properties:
        clientID:
          type: string
        clientSecret:
          type: string
        authURL:
          type: string
          format: uri
        tokenURL:
          type: string
          format: uri
    CreateServerResourceResponse:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/ServerResource'
    UpdateServerResponse:
      type: object
      properties:
        server:
          $ref: '#/components/schemas/Server'
    CreateServerResponse:
      type: object
      properties:
        server:
          $ref: '#/components/schemas/Server'
    UpdateServerRequest:
      type: object
      properties:
        server:
          $ref: '#/components/schemas/ServerCreate'
    ServerPrompt:
      type: object
      properties:
        serverID:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
        promptID:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
    CreateServerTokenRequest:
      type: object
      properties:
        token:
          $ref: '#/components/schemas/ServerTokenCreate'
    CreateServerRequest:
      type: object
      properties:
        server:
          $ref: '#/components/schemas/ServerCreate'
    Provider:
      type: object
      properties:
        id:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        version:
          type: integer
          format: int32
          readOnly: true
        apiType:
          type: string
          description: '0: INVALID, 1: REST'
          example: REST
        visibilityType:
          type: string
          description: '0: INVALID, 1: INTERNAL, 2: PUBLIC'
          example: PUBLIC
        baseURL:
          type: string
          format: uri
        documentURL:
          type: string
          format: uri
        iconURL:
          type: string
          format: uri
        secretPrefix:
          type: string
          readOnly: true
        name:
          type: string
        description:
          type: string
        tools:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/ProviderTool'
        oauth2Config:
          $ref: '#/components/schemas/ProviderOAuth2Config'
    CreateServerResourceRequest:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/ServerResource'
    ServerTool:
      type: object
      properties:
        serverID:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
        providerID:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
        toolID:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
    GetServerResponse:
      type: object
      properties:
        server:
          $ref: '#/components/schemas/Server'
    CreateServerPromptRequest:
      type: object
      properties:
        prompt:
          $ref: '#/components/schemas/ServerPrompt'
    ToolHeader:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
    CreateServerPromptResponse:
      type: object
      properties:
        prompt:
          $ref: '#/components/schemas/ServerPrompt'
    ListServerToolsResponse:
      type: object
      properties:
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ServerTool'
    CreateServerToolRequest:
      type: object
      properties:
        tool:
          $ref: '#/components/schemas/ServerTool'
    ProviderTool:
      type: object
      properties:
        id:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
          readOnly: true
        providerID:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
        method:
          type: string
          example: GET
        path:
          type: string
          example: /users/{id}
        name:
          type: string
          description: MCP tool name (camelCase up to 20chars)
          example: makePayment
        title:
          type: string
          description: MCP tool title (Free text up to 64 chars)
          example: Make Payment
        description:
          type: string
        pathArgsJSONSchema:
          type: object
          description: A raw JSON schema.
          additionalProperties: true
        queryArgsJSONSchema:
          type: object
          description: A raw JSON schema.
          additionalProperties: true
        reqBodyJSONSchema:
          type: object
          description: A raw JSON schema.
          additionalProperties: true
        headers:
          type: array
          items:
            $ref: '#/components/schemas/ToolHeader'
        oauth2Scopes:
          type: array
          items:
            type: string
    ListServersResponse:
      type: object
      properties:
        servers:
          type: array
          items:
            $ref: '#/components/schemas/Server'
    ServerResource:
      type: object
      properties:
        serverID:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
        resourceID:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
    ProviderPrompt:
      type: object
      properties:
        id:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        name:
          type: string
        description:
          type: string
        arguments:
          type: object
          description: A raw JSON message for arguments (e.g., []PromptArgument).
          additionalProperties: true
        messages:
          type: object
          description: A raw JSON message for messages (e.g., []PromptMessage).
          additionalProperties: true
    ListServerPromptsResponse:
      type: object
      properties:
        prompts:
          type: array
          items:
            $ref: '#/components/schemas/ServerPrompt'
    ServerToken:
      type: object
      properties:
        id:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
          readOnly: true
        serverID:
          type: string
          pattern: ^[A-Za-z0-9]{11}$
          example: kSuB9Gf6aD4
        createdAt:
          type: string
          format: date-time
          readOnly: true
        expiresAt:
          type: string
          format: date-time
        name:
          type: string
        value:
          type: string
          description: Token value, only present on creation.
          readOnly: true
    CreateServerToolResponse:
      type: object
      properties:
        tool:
          $ref: '#/components/schemas/ServerTool'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Enter 'Bearer' followed by a space and your token (e.g., 'Bearer ${HASMCP_ACCESS_TOKEN}').
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.hasmcp.com/oauth2/auth
          tokenUrl: https://accounts.hasmcp.com/oauth2/token
          scopes:
            gitconnection:list: List Git connections
            gitconnection:delete: Delete Git connection
            variable:list: List variables
            variable:create: Create variable
            variable:update: Update variable
            variable:delete: Delete variable
            provider:list: List providers
            provider:create: Create provider
            provider:read: Get provider
            provider:update: Update provider
            provider:delete: Delete provider
            server:list: List MCP servers
            server:create: Create MCP server
            server:read: Get MCP server
            server:update: Update MCP server
            server:delete: Delete MCP server
            server:create_token: Create MCP server token