# MCP API schemas

MCPAuthType:
  type: string
  enum: [none, headers, oauth, per_user_oauth]
  description: |
    Authentication type for MCP connections:
    - none: No authentication
    - headers: Header-based authentication (API keys, custom headers, etc.)
    - oauth: OAuth 2.0 authentication (server-level, admin authenticates once)
    - per_user_oauth: Per-user OAuth 2.0 authentication (each user authenticates individually)

MCPConnectionType:
  type: string
  enum: [http, stdio, sse, inprocess]
  description: Connection type for MCP client

MCPConnectionState:
  type: string
  enum: [connected, disconnected, error]
  description: Connection state of an MCP client

MCPStdioConfig:
  type: object
  description: STDIO configuration for MCP client
  properties:
    command:
      type: string
      description: Executable command to run
    args:
      type: array
      items:
        type: string
      description: Command line arguments
    envs:
      type: array
      items:
        type: string
      description: Environment variables required

MCPClientCreateRequest:
  oneOf:
    - $ref: '#/MCPClientCreateRequestHTTP'
    - $ref: '#/MCPClientCreateRequestSSE'
    - $ref: '#/MCPClientCreateRequestSTDIO'
  discriminator:
    propertyName: connection_type
    mapping:
      http: '#/MCPClientCreateRequestHTTP'
      sse: '#/MCPClientCreateRequestSSE'
      stdio: '#/MCPClientCreateRequestSTDIO'
  description: |
    MCP client configuration for creating a new client (tool_pricing not available at creation).
    The schema varies based on connection_type:
    - HTTP/SSE: connection_string is required
    - STDIO: stdio_config is required
    - InProcess: server instance must be provided programmatically (Go package only)

MCPClientCreateRequestBase:
  type: object
  required:
    - name
    - connection_type
  properties:
    client_id:
      type: string
      description: Unique identifier for the MCP client (optional, auto-generated if not provided)
    name:
      type: string
      description: Display name for the MCP client
    is_code_mode_client:
      type: boolean

    is_ping_available:
      type: boolean
      default: true
      description: |
        Whether the MCP server supports ping for health checks.
        If true, uses lightweight ping method for health checks.
        If false, uses listTools method for health checks instead.
    connection_type:
      $ref: '#/MCPConnectionType'
    auth_type:
      $ref: '#/MCPAuthType'
      description: Authentication type for the MCP connection
    oauth_config_id:
      type: string
      description: |
        OAuth config ID for OAuth authentication.
        Set after OAuth flow is completed. References the oauth_configs table.
        Only relevant when auth_type is "oauth".
    headers:
      type: object
      additionalProperties:
        type: string
      description: |
        Custom headers to include in requests.
        Only used when auth_type is "headers".
    oauth_config:
      $ref: '../../schemas/management/oauth.yaml#/OAuthConfigRequest'
      description: |
        OAuth configuration for initiating OAuth flow.
        Only include this when creating a client with auth_type "oauth".
        This will trigger the OAuth flow and return an authorization URL.
    tools_to_execute:
      type: array
      items:
        type: string
      description: |
        Include-only list for tools.
        ["*"] => all tools are included
        [] => no tools are included
        ["tool1", "tool2"] => include only the specified tools
    tools_to_auto_execute:
      type: array
      items:
        type: string
      description: |
        List of tools that can be auto-executed without user approval.
        Must be a subset of tools_to_execute.
        ["*"] => all executable tools can be auto-executed
        [] => no tools are auto-executed
        ["tool1", "tool2"] => only specified tools can be auto-executed
    allow_on_all_virtual_keys:
      type: boolean
      default: false
      description: |
        When true, this MCP client's tools are available to all virtual keys by default,
        without requiring an explicit virtual key assignment.
        An explicit virtual key config always overrides this setting for that key.
MCPClientCreateRequestHTTP:
  allOf:
    - $ref: '#/MCPClientCreateRequestBase'
    - type: object
      required:
        - connection_string
      properties:
        connection_type:
          type: string
          enum: [http]
        connection_string:
          type: string
          description: HTTP URL (required for HTTP connection type)

MCPClientCreateRequestSSE:
  allOf:
    - $ref: '#/MCPClientCreateRequestBase'
    - type: object
      required:
        - connection_string
      properties:
        connection_type:
          type: string
          enum: [sse]
        connection_string:
          type: string
          description: SSE URL (required for SSE connection type)

MCPClientCreateRequestSTDIO:
  allOf:
    - $ref: '#/MCPClientCreateRequestBase'
    - type: object
      required:
        - stdio_config
      properties:
        connection_type:
          type: string
          enum: [stdio]
        stdio_config:
          $ref: '#/MCPStdioConfig'
          description: STDIO configuration (required for STDIO connection type)

MCPClientUpdateRequest:
  type: object
  description: MCP client configuration for updating an existing client (includes tool_pricing)
  properties:
    client_id:
      type: string
      description: Unique identifier for the MCP client
    name:
      type: string
      description: Display name for the MCP client
    is_code_mode_client:
      type: boolean
      description: Whether this client is available in code mode
    connection_type:
      $ref: '#/MCPConnectionType'
    connection_string:
      type: string
      description: HTTP or SSE URL (required for HTTP or SSE connections)
    stdio_config:
      $ref: '#/MCPStdioConfig'
    auth_type:
      $ref: '#/MCPAuthType'
      description: Authentication type for the MCP connection
    oauth_config_id:
      type: string
      description: |
        OAuth config ID for OAuth authentication.
        References the oauth_configs table.
        Only relevant when auth_type is "oauth".
    headers:
      type: object
      additionalProperties:
        type: string
      description: |
        Custom headers to include in requests.
        Only used when auth_type is "headers".
    tools_to_execute:
      type: array
      items:
        type: string
      description: |
        Include-only list for tools.
        ["*"] => all tools are included
        [] => no tools are included
        ["tool1", "tool2"] => include only the specified tools
    tools_to_auto_execute:
      type: array
      items:
        type: string
      description: |
        List of tools that can be auto-executed without user approval.
        Must be a subset of tools_to_execute.
        ["*"] => all executable tools can be auto-executed
        [] => no tools are auto-executed
        ["tool1", "tool2"] => only specified tools can be auto-executed
    tool_pricing:
      type: object
      additionalProperties:
        type: number
        format: double
      description: |
        Per-tool cost in USD for execution.
        Key is the tool name, value is the cost per execution.
        Example: {"read_file": 0.001, "write_file": 0.002}
        Note: Only available when updating an existing client after tools have been fetched.
    allow_on_all_virtual_keys:
      type: boolean
      default: false
      description: |
        When true, this MCP client's tools are accessible to all virtual keys without requiring
        explicit per-key assignment. All tools are allowed by default. If a virtual key has an
        explicit MCP config for this client, that config takes precedence and overrides this behaviour.
    vk_configs:
      type: array
      items:
        $ref: '#/MCPVKConfig'
      description: |
        When provided, replaces all virtual key assignments for this MCP client.
        Each entry specifies a virtual key and the tools it is allowed to call.
        To remove all VK access, provide an empty array [].
        Omit this field to leave existing VK assignments unchanged.

MCPVKConfig:
  type: object
  description: Per-virtual-key tool access configuration for an MCP client
  required:
    - virtual_key_id
    - tools_to_execute
  properties:
    virtual_key_id:
      type: string
      description: ID of the virtual key
    tools_to_execute:
      type: array
      items:
        type: string
      description: |
        Tools this virtual key is allowed to call on this MCP server.
        ["*"] => all tools allowed
        ["tool1", "tool2"] => only the specified tools

MCPClientConfig:
  type: object
  description: Full MCP client configuration (used in responses)
  properties:
    client_id:
      type: string
      description: Unique identifier for the MCP client
    name:
      type: string
      description: Display name for the MCP client
    is_code_mode_client:
      type: boolean
      description: Whether this client is available in code mode
    connection_type:
      $ref: '#/MCPConnectionType'
    connection_string:
      type: string
      description: HTTP or SSE URL (required for HTTP or SSE connections)
    stdio_config:
      $ref: '#/MCPStdioConfig'
    auth_type:
      $ref: '#/MCPAuthType'
      description: Authentication type for the MCP connection
    oauth_config_id:
      type: string
      description: |
        OAuth config ID for OAuth authentication.
        References the oauth_configs table.
        Only set when auth_type is "oauth".
    headers:
      type: object
      additionalProperties:
        type: string
      description: |
        Custom headers to include in requests.
        Only used when auth_type is "headers".
    tools_to_execute:
      type: array
      items:
        type: string
      description: |
        Include-only list for tools.
        ["*"] => all tools are included
        [] => no tools are included
        ["tool1", "tool2"] => include only the specified tools
    tools_to_auto_execute:
      type: array
      items:
        type: string
      description: |
        List of tools that can be auto-executed without user approval.
        Must be a subset of tools_to_execute.
        ["*"] => all executable tools can be auto-executed
        [] => no tools are auto-executed
        ["tool1", "tool2"] => only specified tools can be auto-executed
    tool_pricing:
      type: object
      additionalProperties:
        type: number
        format: double
      description: |
        Per-tool cost in USD for execution.
        Key is the tool name, value is the cost per execution.
        Example: {"read_file": 0.001, "write_file": 0.002}
    allow_on_all_virtual_keys:
      type: boolean
      default: false
      description: |
        When true, this MCP client's tools are accessible to all virtual keys without requiring
        explicit per-key assignment. All tools are allowed by default. If a virtual key has an
        explicit MCP config for this client, that config takes precedence and overrides this behaviour.

ChatToolFunction:
  type: object
  description: Tool function definition
  properties:
    name:
      type: string
    description:
      type: string
    parameters:
      type: object
      additionalProperties: true
    strict:
      type: boolean

MCPVKConfigResponse:
  type: object
  description: Per-virtual-key tool access configuration as returned in list/get responses
  properties:
    virtual_key_id:
      type: string
      description: ID of the virtual key
    virtual_key_name:
      type: string
      description: Display name of the virtual key
    tools_to_execute:
      type: array
      items:
        type: string
      description: |
        Tools this virtual key is allowed to call on this MCP client.
        ["*"] => all tools allowed
        ["tool1", "tool2"] => only the specified tools

MCPClient:
  type: object
  description: Connected MCP client with its tools
  properties:
    config:
      $ref: '#/MCPClientConfig'
    tools:
      type: array
      items:
        $ref: '#/ChatToolFunction'
    state:
      $ref: '#/MCPConnectionState'
    vk_configs:
      type: array
      items:
        $ref: '#/MCPVKConfigResponse'
      description: Virtual key assignments for this MCP client

ExecuteToolRequest:
  oneOf:
    - title: Chat (Default)
      description: Chat format - uses ChatAssistantMessageToolCall schema
      $ref: '../../schemas/inference/chat.yaml#/ChatAssistantMessageToolCall'
    - title: Responses
      description: Responses format - uses ResponsesToolMessage schema
      $ref: '#/ResponsesToolMessage'
  description: |
    MCP tool execution request. The schema depends on the `format` query parameter:
    - `format=chat` or empty (default): Use `ChatAssistantMessageToolCall` schema
    - `format=responses`: Use `ResponsesToolMessage` schema

ExecuteToolResponse:
  oneOf:
    - title: Chat (Default)
      description: Chat format response
      $ref: '../../schemas/inference/chat.yaml#/ChatMessage'
    - title: Responses
      description: Responses format response
      $ref: '../../schemas/inference/responses.yaml#/ResponsesMessage'
  description: |
    MCP tool execution response.

ResponsesToolMessage:
  type: object
  description: Tool message for Responses API format
  required:
    - name
  properties:
    call_id:
      type: string
      description: Common call ID for tool calls and outputs
    name:
      type: string
      description: Tool function name (required for execution)
    arguments:
      type: string
      description: Tool function arguments as JSON string
    output:
      type: object
      description: Tool execution output
      additionalProperties: true
    action:
      type: object
      description: Tool action configuration
      additionalProperties: true
    error:
      type: string
      description: Error message if tool execution failed