execute-tool:
  post:
    operationId: executeMCPTool
    summary: Execute MCP tool
    description: Executes an MCP tool and returns the result.
    tags:
      - MCP
    parameters:
      - name: format
        in: query
        required: false
        description: |
          Format of the tool execution request/response.
        schema:
          type: string
          enum: [chat, responses]
          default: chat
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../../schemas/management/mcp.yaml#/ExecuteToolRequest'
          examples:
            chat:
              summary: Chat format example
              value:
                id: "call_123"
                type: "function"
                function:
                  name: "get_weather"
                  arguments: '{"location": "San Francisco"}'
            responses:
              summary: Responses format example
              value:
                call_id: "call_123"
                name: "get_weather"
                arguments: '{"location": "San Francisco"}'
    responses:
      '200':
        description: Tool executed successfully
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/mcp.yaml#/ExecuteToolResponse'
            examples:
              chat:
                summary: Chat format response
                value:
                  name: "get_weather"
                  role: "tool"
                  tool_call_id: "call_123"
                  content: "The weather in San Francisco is 72°F and sunny."
              responses:
                summary: Responses format response
                value:
                  id: "msg_123"
                  type: "function_call_output"
                  status: "completed"
                  role: "assistant"
                  call_id: "call_123"
                  name: "get_weather"
                  arguments: '{"location": "San Francisco"}'
                  content: "The weather in San Francisco is 72°F and sunny."
      '400':
        $ref: '../../openapi.yaml#/components/responses/BadRequest'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'
    security:
      - BearerAuth: []
      - BasicAuth: []
      - VirtualKeyAuth: []
      - ApiKeyAuth: []

clients:
  get:
    operationId: getMCPClients
    summary: List MCP clients
    description: Returns a list of all configured MCP clients with their tools and connection state.
    tags:
      - MCP
    responses:
      '200':
        description: Successful response
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '../../schemas/management/mcp.yaml#/MCPClient'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

client:
  post:
    operationId: addMCPClient
    summary: Add MCP client
    description: |
      Adds a new MCP client with the specified configuration.
      Note: tool_pricing is not available when creating a new client as tools are fetched after client creation.
    tags:
      - MCP
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../../schemas/management/mcp.yaml#/MCPClientCreateRequest'
    responses:
      '200':
        description: MCP client added successfully
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/SuccessResponse'
      '400':
        $ref: '../../openapi.yaml#/components/responses/BadRequest'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

client-by-id:
  put:
    operationId: editMCPClient
    summary: Edit MCP client
    description: |
      Updates an existing MCP client's configuration.
      Unlike client creation, tool_pricing can be included to set per-tool execution costs since tools are already fetched.
      Optionally provide vk_configs to manage which virtual keys have access to this MCP server and with which tools. When provided, this fully replaces all existing VK assignments in a single atomic transaction.
    tags:
      - MCP
    parameters:
      - name: id
        in: path
        required: true
        description: MCP client ID
        schema:
          type: string
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../../schemas/management/mcp.yaml#/MCPClientUpdateRequest'
    responses:
      '200':
        description: MCP client updated successfully
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/SuccessResponse'
      '400':
        $ref: '../../openapi.yaml#/components/responses/BadRequest'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

  delete:
    operationId: removeMCPClient
    summary: Remove MCP client
    description: Removes an MCP client from the configuration.
    tags:
      - MCP
    parameters:
      - name: id
        in: path
        required: true
        description: MCP client ID
        schema:
          type: string
    responses:
      '200':
        description: MCP client removed successfully
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/SuccessResponse'
      '400':
        $ref: '../../openapi.yaml#/components/responses/BadRequest'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

client-reconnect:
  post:
    operationId: reconnectMCPClient
    summary: Reconnect MCP client
    description: Reconnects an MCP client that is in an error or disconnected state.
    tags:
      - MCP
    parameters:
      - name: id
        in: path
        required: true
        description: MCP client ID
        schema:
          type: string
    responses:
      '200':
        description: MCP client reconnected successfully
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/SuccessResponse'
      '400':
        $ref: '../../openapi.yaml#/components/responses/BadRequest'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'

client-complete-oauth:
  post:
    operationId: completeMCPClientOAuth
    summary: Complete MCP client OAuth flow
    description: |
      Completes the OAuth flow for an MCP client after the user has authorized the request.
      This endpoint should be called after the OAuth provider redirects back to the callback endpoint
      and the OAuth token has been stored. It retrieves the pending MCP client configuration and
      establishes the connection with the OAuth-provided credentials.
    tags:
      - MCP
      - OAuth
    parameters:
      - name: id
        in: path
        required: true
        description: MCP client ID
        schema:
          type: string
    responses:
      '200':
        description: MCP client connected successfully with OAuth
        content:
          application/json:
            schema:
              $ref: '../../schemas/management/common.yaml#/SuccessResponse'
      '400':
        description: OAuth not authorized yet or MCP client not found in pending OAuth clients
        $ref: '../../openapi.yaml#/components/responses/BadRequest'
      '404':
        description: MCP client not found in pending OAuth clients or OAuth config not found
        $ref: '../../openapi.yaml#/components/responses/NotFound'
      '500':
        $ref: '../../openapi.yaml#/components/responses/InternalError'