components:
  schemas:
    config.Config:
      properties:
        activity_cleanup_interval_min:
          description: 'Background cleanup interval in minutes (default: 60)'
          type: integer
        activity_max_records:
          description: 'Max records before pruning (default: 100000)'
          type: integer
        activity_max_response_size:
          description: 'Response truncation limit in bytes (default: 65536)'
          type: integer
        activity_retention_days:
          description: Activity logging settings (RFC-003)
          type: integer
        allow_server_add:
          type: boolean
        allow_server_remove:
          type: boolean
        api_key:
          description: Security settings
          type: string
        call_tool_timeout:
          type: string
        check_server_repo:
          description: Repository detection settings
          type: boolean
        code_execution_max_tool_calls:
          description: 'Max tool calls per execution (0 = unlimited, default: 0)'
          type: integer
        code_execution_pool_size:
          description: 'JavaScript runtime pool size (default: 10)'
          type: integer
        code_execution_timeout_ms:
          description: 'Timeout in milliseconds (default: 120000, max: 600000)'
          type: integer
        data_dir:
          type: string
        debug_search:
          type: boolean
        disable_management:
          type: boolean
        docker_isolation:
          $ref: '#/components/schemas/config.DockerIsolationConfig'
        docker_recovery:
          $ref: '#/components/schemas/config.DockerRecoveryConfig'
        enable_code_execution:
          description: Code execution settings
          type: boolean
        enable_prompts:
          description: Prompts settings
          type: boolean
        enable_socket:
          description: 'Enable Unix socket/named pipe for local IPC (default: true)'
          type: boolean
        enable_tray:
          description: 'Deprecated: EnableTray is unused and has no runtime effect.
            Kept for backward compatibility.'
          type: boolean
        environment:
          $ref: '#/components/schemas/secureenv.EnvConfig'
        features:
          $ref: '#/components/schemas/config.FeatureFlags'
        intent_declaration:
          $ref: '#/components/schemas/config.IntentDeclarationConfig'
        listen:
          type: string
        logging:
          $ref: '#/components/schemas/config.LogConfig'
        max_result_size_chars:
          description: Advertised on every tool as `_meta.anthropic/maxResultSizeChars`;
            raises Claude Code's inline-response ceiling from 50k to up to 500k chars.
            Set to 0 to disable.
          type: integer
        mcpServers:
          items:
            $ref: '#/components/schemas/config.ServerConfig'
          type: array
          uniqueItems: false
        oauth_expiry_warning_hours:
          description: Health status settings
          type: number
        quarantine_enabled:
          description: |-
            QuarantineEnabled controls whether quarantine is active. It gates two
            things together:
              1. Server-level auto-quarantine for newly added servers (issue #370).
                 When true, servers added via the upstream_servers MCP tool or the
                 REST API default to quarantined=true; when false, they default to
                 quarantined=false. Explicit per-request values always win.
              2. Tool-level quarantine (Spec 032): per-tool SHA-256 approval of
                 tool descriptions/schemas.
            When nil (default), quarantine is enabled (secure by default). Set to
            explicit false to opt out of both. Per-server SkipQuarantine still
            applies for the tool-level check on individual servers.
          type: boolean
        read_only_mode:
          type: boolean
        registries:
          description: Registries configuration for MCP server discovery
          items:
            $ref: '#/components/schemas/config.RegistryEntry'
          type: array
          uniqueItems: false
        require_mcp_auth:
          description: 'Require authentication on /mcp endpoint (default: false)'
          type: boolean
        reveal_secret_headers:
          description: |-
            RevealSecretHeaders, when true, disables the redaction of sensitive
            header values (Authorization, X-API-Key, Cookie, …) in responses
            from the `upstream_servers` MCP tool, the `/api/v1/servers` REST
            API, and the SSE event stream.

            Default false — sensitive header values are surfaced as
            `***REDACTED***` so an MCP agent cannot read Bearer tokens / API
            keys out of another upstream's config (PR #425).

            The Web UI / macOS tray edit forms work without seeing the real
            values: PATCH /api/v1/servers/{id} deep-merges (omitted keys are
            preserved, see `headers_remove` / `env_remove` for explicit
            deletes), so clients compute a diff and only send the keys that
            actually changed. Redacted-but-unchanged values never round-trip
            — the backend keeps the real string. Set this to true if a
            downstream tool genuinely needs raw values in the response.
          type: boolean
        routing_mode:
          description: |-
            Routing mode (Spec 031): how MCP tools are exposed to clients
            Valid values: "retrieve_tools" (default), "direct", "code_execution"
          type: string
        security:
          $ref: '#/components/schemas/config.SecurityConfig'
        sensitive_data_detection:
          $ref: '#/components/schemas/config.SensitiveDataDetectionConfig'
        telemetry:
          $ref: '#/components/schemas/config.TelemetryConfig'
        tls:
          $ref: '#/components/schemas/config.TLSConfig'
        tokenizer:
          $ref: '#/components/schemas/config.TokenizerConfig'
        tool_response_limit:
          type: integer
        tool_response_session_risk_warning:
          description: |-
            ToolResponseSessionRiskWarning controls whether the prose `warning` field
            is included in the `session_risk` object returned by `retrieve_tools`.
            The structured fields (level, lethal_trifecta, has_open_world_tools, etc.)
            are always included. Default: false (quiet for LLM clients) — see issue #406.
            Most tools lack annotations, so the MCP-spec defaults treat them as fully
            permissive across all three risk axes, which makes the prose warning fire
            on almost every call and wastes tokens.
          type: boolean
        tools_limit:
          type: integer
        top_k:
          description: 'Deprecated: TopK is superseded by ToolsLimit and has no runtime
            effect. Kept for backward compatibility.'
          type: integer
        tray_endpoint:
          description: Tray endpoint override (unix:// or npipe://)
          type: string
      type: object
    config.CustomPattern:
      properties:
        category:
          description: Category (defaults to "custom")
          type: string
        keywords:
          description: Keywords to match (mutually exclusive with Regex)
          items:
            type: string
          type: array
          uniqueItems: false
        name:
          description: Unique identifier for this pattern
          type: string
        regex:
          description: Regex pattern (mutually exclusive with Keywords)
          type: string
        severity:
          description: 'Risk level: critical, high, medium, low'
          type: string
      type: object
    config.DockerIsolationConfig:
      description: Docker isolation settings
      properties:
        cpu_limit:
          description: CPU limit for containers
          type: string
        default_images:
          additionalProperties:
            type: string
          description: Map of runtime type to Docker image
          type: object
        enable_cache_volume:
          description: 'Mount shared cache volumes for faster restarts (default: true)'
          type: boolean
        enabled:
          description: Global enable/disable for Docker isolation
          type: boolean
        extra_args:
          description: Additional docker run arguments
          items:
            type: string
          type: array
          uniqueItems: false
        log_driver:
          description: 'Docker log driver (default: json-file)'
          type: string
        log_max_files:
          description: 'Maximum number of log files (default: 3)'
          type: string
        log_max_size:
          description: 'Maximum size of log files (default: 100m)'
          type: string
        memory_limit:
          description: Memory limit for containers
          type: string
        network_mode:
          description: 'Docker network mode (default: bridge)'
          type: string
        registry:
          description: Custom registry (defaults to docker.io)
          type: string
        timeout:
          description: Container startup timeout
          type: string
      type: object
    config.DockerRecoveryConfig:
      description: Docker recovery settings
      properties:
        enabled:
          description: 'Enable Docker recovery monitoring (default: true)'
          type: boolean
        max_retries:
          description: Maximum retry attempts (0 = unlimited)
          type: integer
        notify_on_failure:
          description: 'Show notification on recovery failure (default: true)'
          type: boolean
        notify_on_retry:
          description: 'Show notification on each retry (default: false)'
          type: boolean
        notify_on_start:
          description: 'Show notification when recovery starts (default: true)'
          type: boolean
        notify_on_success:
          description: 'Show notification on successful recovery (default: true)'
          type: boolean
        persistent_state:
          description: 'Save recovery state across restarts (default: true)'
          type: boolean
      type: object
    config.FeatureFlags:
      description: 'Deprecated: Features flags are unused and have no runtime effect.
        Kept for backward compatibility.'
      properties:
        enable_async_storage:
          type: boolean
        enable_caching:
          type: boolean
        enable_contract_tests:
          type: boolean
        enable_debug_logging:
          description: Development features
          type: boolean
        enable_docker_isolation:
          type: boolean
        enable_event_bus:
          type: boolean
        enable_health_checks:
          type: boolean
        enable_metrics:
          type: boolean
        enable_oauth:
          description: Security features
          type: boolean
        enable_observability:
          description: Observability features
          type: boolean
        enable_quarantine:
          type: boolean
        enable_runtime:
          description: Runtime features
          type: boolean
        enable_search:
          description: Storage features
          type: boolean
        enable_sse:
          type: boolean
        enable_tracing:
          type: boolean
        enable_tray:
          type: boolean
        enable_web_ui:
          description: UI features
          type: boolean
      type: object
    config.IntentDeclarationConfig:
      description: Intent declaration settings (Spec 018)
      properties:
        strict_server_validation:
          description: |-
            StrictServerValidation controls whether server annotation mismatches
            cause rejection (true) or just warnings (false).
            Default: true (reject mismatches)
          type: boolean
      type: object
    config.IsolationConfig:
      description: Per-server isolation settings
      properties:
        enabled:
          description: Enable Docker isolation for this server (nil = inherit global)
          type: boolean
        extra_args:
          description: Additional docker run arguments for this server
          items:
            type: string
          type: array
          uniqueItems: false
        image:
          description: Custom Docker image (overrides default)
          type: string
        log_driver:
          description: Docker log driver override for this server
          type: string
        log_max_files:
          description: Maximum number of log files override
          type: string
        log_max_size:
          description: Maximum size of log files override
          type: string
        network_mode:
          description: Custom network mode for this server
          type: string
        working_dir:
          description: Custom working directory in container
          type: string
      type: object
    config.LogConfig:
      description: Logging configuration
      properties:
        compress:
          type: boolean
        enable_console:
          type: boolean
        enable_file:
          type: boolean
        filename:
          type: string
        json_format:
          type: boolean
        level:
          type: string
        log_dir:
          description: Custom log directory
          type: string
        max_age:
          description: days
          type: integer
        max_backups:
          description: number of backup files
          type: integer
        max_size:
          description: MB
          type: integer
      type: object
    config.OAuthConfig:
      description: OAuth configuration (keep even when empty to signal OAuth requirement)
      properties:
        client_id:
          type: string
        client_secret:
          type: string
        extra_params:
          additionalProperties:
            type: string
          description: Additional OAuth parameters (e.g., RFC 8707 resource)
          type: object
        pkce_enabled:
          type: boolean
        redirect_uri:
          type: string
        scopes:
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    config.RegistryEntry:
      properties:
        count:
          description: number or string
          type: string
        description:
          type: string
        id:
          type: string
        name:
          type: string
        protocol:
          type: string
        servers_url:
          type: string
        tags:
          items:
            type: string
          type: array
          uniqueItems: false
        url:
          type: string
      type: object
    config.SecurityConfig:
      description: Security scanner settings (Spec 039)
      properties:
        auto_scan_quarantined:
          type: boolean
        integrity_check_interval:
          type: string
        integrity_check_on_restart:
          type: boolean
        runtime_read_only:
          type: boolean
        runtime_tmpfs_size:
          type: string
        scan_timeout_default:
          type: string
        scanner_disable_no_new_privileges:
          description: |-
            ScannerDisableNoNewPrivileges, when true, omits the
            `--security-opt no-new-privileges` flag from scanner container runs.

            Background: snap-installed Docker on Ubuntu confines dockerd under the
            `snap.docker.dockerd` AppArmor profile. When runc tries to transition
            the container into the inner `docker-default` profile to exec the
            entrypoint, AppArmor refuses the transition because NO_NEW_PRIVS
            forbids privilege/profile changes on exec — the result is EPERM
            ("operation not permitted") and every scanner fails immediately.

            Set this to true ONLY on hosts hitting that incompatibility. Scanner
            containers still run with read-only rootfs, tmpfs /tmp, no-network by
            default, and read-only source mounts, so the marginal isolation loss
            is small. The preferred fix remains replacing snap docker with a
            distro-packaged docker.
          type: boolean
        scanner_registry_url:
          type: string
      type: object
    config.SensitiveDataDetectionConfig:
      description: Sensitive data detection settings (Spec 026)
      properties:
        categories:
          additionalProperties:
            type: boolean
          description: Enable/disable specific detection categories
          type: object
        custom_patterns:
          description: User-defined detection patterns
          items:
            $ref: '#/components/schemas/config.CustomPattern'
          type: array
          uniqueItems: false
        enabled:
          description: 'Enable sensitive data detection (default: true)'
          type: boolean
        entropy_threshold:
          description: 'Shannon entropy threshold for high-entropy detection (default:
            4.5)'
          type: number
        max_payload_size_kb:
          description: 'Max size to scan before truncating (default: 1024)'
          type: integer
        scan_requests:
          description: 'Scan tool call arguments (default: true)'
          type: boolean
        scan_responses:
          description: 'Scan tool responses (default: true)'
          type: boolean
        sensitive_keywords:
          description: Keywords to flag
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    config.ServerConfig:
      properties:
        args:
          items:
            type: string
          type: array
          uniqueItems: false
        command:
          type: string
        created:
          type: string
        disabled_tools:
          description: 'Denylist: these tools are hidden; mutually exclusive with
            enabled_tools'
          items:
            type: string
          type: array
          uniqueItems: false
        enabled:
          type: boolean
        enabled_tools:
          description: 'Allowlist: only these tools are exposed; mutually exclusive
            with disabled_tools'
          items:
            type: string
          type: array
          uniqueItems: false
        env:
          additionalProperties:
            type: string
          type: object
        headers:
          additionalProperties:
            type: string
          description: For HTTP servers
          type: object
        isolation:
          $ref: '#/components/schemas/config.IsolationConfig'
        launcher_wait_timeout:
          description: |-
            LauncherWaitTimeout caps how long mcpproxy will wait for a locally-launched
            HTTP/SSE upstream's URL to become reachable after Spawn(). Only consulted
            when the server is configured with both Command and an HTTP/SSE URL — i.e.,
            mcpproxy starts the process AND connects via network. Stdio servers ignore
            this field. Zero or unset → 30s default.
          type: string
        name:
          type: string
        oauth:
          $ref: '#/components/schemas/config.OAuthConfig'
        protocol:
          description: stdio, http, sse, streamable-http, auto
          type: string
        quarantined:
          description: Security quarantine status
          type: boolean
        reconnect_on_use:
          description: Attempt reconnection when a tool call targets a disconnected
            server
          type: boolean
        shared:
          description: 'Server edition: shared with all users'
          type: boolean
        skip_quarantine:
          description: Skip tool-level quarantine for this server
          type: boolean
        updated:
          type: string
        url:
          type: string
        working_dir:
          description: Working directory for stdio servers
          type: string
      type: object
    config.TLSConfig:
      description: TLS configuration
      properties:
        certs_dir:
          description: Directory for certificates
          type: string
        enabled:
          description: Enable HTTPS
          type: boolean
        hsts:
          description: Enable HTTP Strict Transport Security
          type: boolean
        require_client_cert:
          description: Enable mTLS
          type: boolean
      type: object
    config.TelemetryConfig:
      description: Telemetry settings (Spec 036)
      properties:
        anonymous_id:
          description: Auto-generated UUIDv4
          type: string
        anonymous_id_created_at:
          description: Spec 042 (Tier 2) additions — all default-zero, all backwards-compatible.
          type: string
        enabled:
          description: 'Default: true (opt-out)'
          type: boolean
        endpoint:
          description: Override for testing
          type: string
        last_reported_version:
          description: Upgrade funnel
          type: string
        last_startup_outcome:
          description: success|port_conflict|db_locked|...
          type: string
        notice_shown:
          description: First-run notice flag
          type: boolean
      type: object
    config.TokenizerConfig:
      description: Tokenizer configuration for token counting
      properties:
        default_model:
          description: Default model for tokenization (e.g., "gpt-4")
          type: string
        enabled:
          description: Enable token counting
          type: boolean
        encoding:
          description: Default encoding (e.g., "cl100k_base")
          type: string
      type: object
    configimport.FailedServer:
      properties:
        details:
          type: string
        error:
          type: string
        name:
          type: string
      type: object
    configimport.ImportSummary:
      properties:
        failed:
          type: integer
        imported:
          type: integer
        skipped:
          type: integer
        total:
          type: integer
      type: object
    configimport.SkippedServer:
      properties:
        name:
          type: string
        reason:
          description: '"already_exists", "filtered_out", "invalid_name"'
          type: string
      type: object
    contracts.APIResponse:
      allOf:
      - $ref: '#/components/schemas/data'
      properties:
        data:
          type: object
        error:
          type: string
        request_id:
          type: string
        success:
          type: boolean
      type: object
    contracts.ActivityDetailResponse:
      properties:
        activity:
          $ref: '#/components/schemas/contracts.ActivityRecord'
      type: object
    contracts.ActivityListResponse:
      properties:
        activities:
          items:
            $ref: '#/components/schemas/contracts.ActivityRecord'
          type: array
          uniqueItems: false
        limit:
          type: integer
        offset:
          type: integer
        total:
          type: integer
      type: object
    contracts.ActivityRecord:
      properties:
        arguments:
          description: Tool call arguments
          type: object
        detection_types:
          description: List of detection types found
          items:
            type: string
          type: array
          uniqueItems: false
        duration_ms:
          description: Execution duration in milliseconds
          type: integer
        error_message:
          description: Error details if status is "error"
          type: string
        has_sensitive_data:
          description: Sensitive data detection fields (Spec 026)
          type: boolean
        id:
          description: Unique identifier (ULID format)
          type: string
        max_severity:
          description: Highest severity level detected (critical, high, medium, low)
          type: string
        metadata:
          description: Additional context-specific data
          type: object
        request_id:
          description: HTTP request ID for correlation
          type: string
        response:
          description: Tool response (potentially truncated)
          type: string
        response_truncated:
          description: True if response was truncated
          type: boolean
        server_name:
          description: Name of upstream MCP server
          type: string
        session_id:
          description: MCP session ID for correlation
          type: string
        source:
          $ref: '#/components/schemas/contracts.ActivitySource'
        status:
          description: 'Result status: "success", "error", "blocked"'
          type: string
        timestamp:
          description: When activity occurred
          type: string
        tool_name:
          description: Name of tool called
          type: string
        type:
          $ref: '#/components/schemas/contracts.ActivityType'
      type: object
    contracts.ActivitySource:
      description: 'How activity was triggered: "mcp", "cli", "api"'
      type: string
      x-enum-varnames:
      - ActivitySourceMCP
      - ActivitySourceCLI
      - ActivitySourceAPI
    contracts.ActivitySummaryResponse:
      properties:
        blocked_count:
          description: Count of blocked activities
          type: integer
        end_time:
          description: End of the period (RFC3339)
          type: string
        error_count:
          description: Count of error activities
          type: integer
        period:
          description: Time period (1h, 24h, 7d, 30d)
          type: string
        start_time:
          description: Start of the period (RFC3339)
          type: string
        success_count:
          description: Count of successful activities
          type: integer
        top_servers:
          description: Top servers by activity count
          items:
            $ref: '#/components/schemas/contracts.ActivityTopServer'
          type: array
          uniqueItems: false
        top_tools:
          description: Top tools by activity count
          items:
            $ref: '#/components/schemas/contracts.ActivityTopTool'
          type: array
          uniqueItems: false
        total_count:
          description: Total activity count
          type: integer
      type: object
    contracts.ActivityTopServer:
      properties:
        count:
          description: Activity count
          type: integer
        name:
          description: Server name
          type: string
      type: object
    contracts.ActivityTopTool:
      properties:
        count:
          description: Activity count
          type: integer
        server:
          description: Server name
          type: string
        tool:
          description: Tool name
          type: string
      type: object
    contracts.ActivityType:
      description: Type of activity
      type: string
      x-enum-varnames:
      - ActivityTypeToolCall
      - ActivityTypePolicyDecision
      - ActivityTypeQuarantineChange
      - ActivityTypeServerChange
    contracts.ConfigApplyResult:
      properties:
        applied_immediately:
          type: boolean
        changed_fields:
          items:
            type: string
          type: array
          uniqueItems: false
        requires_restart:
          type: boolean
        restart_reason:
          type: string
        success:
          type: boolean
        validation_errors:
          items:
            $ref: '#/components/schemas/contracts.ValidationError'
          type: array
          uniqueItems: false
      type: object
    contracts.DCRStatus:
      properties:
        attempted:
          type: boolean
        error:
          type: string
        status_code:
          type: integer
        success:
          type: boolean
      type: object
    contracts.DeprecatedConfigWarning:
      properties:
        field:
          type: string
        message:
          type: string
        replacement:
          type: string
      type: object
    contracts.Diagnostic:
      description: |-
        Spec 044 — structured diagnostic error and stable error code. Both
        are populated when the server is in a failed state and the error
        has been classified by internal/diagnostics. Healthy servers omit
        these fields.
      properties:
        cause:
          type: string
        code:
          type: string
        detected_at:
          type: string
        docs_url:
          type: string
        fix_steps:
          items:
            $ref: '#/components/schemas/contracts.DiagnosticFixStep'
          type: array
          uniqueItems: false
        severity:
          type: string
        user_message:
          type: string
      type: object
    contracts.DiagnosticFixStep:
      properties:
        command:
          type: string
        destructive:
          type: boolean
        fixer_key:
          type: string
        label:
          type: string
        type:
          type: string
        url:
          type: string
      type: object
    contracts.Diagnostics:
      properties:
        deprecated_configs:
          description: Deprecated config fields found
          items:
            $ref: '#/components/schemas/contracts.DeprecatedConfigWarning'
          type: array
          uniqueItems: false
        docker_status:
          $ref: '#/components/schemas/contracts.DockerStatus'
        missing_secrets:
          description: Renamed to avoid conflict
          items:
            $ref: '#/components/schemas/contracts.MissingSecretInfo'
          type: array
          uniqueItems: false
        oauth_issues:
          description: OAuth parameter mismatches
          items:
            $ref: '#/components/schemas/contracts.OAuthIssue'
          type: array
          uniqueItems: false
        oauth_required:
          items:
            $ref: '#/components/schemas/contracts.OAuthRequirement'
          type: array
          uniqueItems: false
        runtime_warnings:
          items:
            type: string
          type: array
          uniqueItems: false
        timestamp:
          type: string
        total_issues:
          type: integer
        upstream_errors:
          items:
            $ref: '#/components/schemas/contracts.UpstreamError'
          type: array
          uniqueItems: false
      type: object
    contracts.DockerStatus:
      properties:
        available:
          type: boolean
        error:
          type: string
        version:
          type: string
      type: object
    contracts.ErrorResponse:
      properties:
        error:
          type: string
        request_id:
          type: string
        success:
          type: boolean
      type: object
    contracts.FindingCounts:
      properties:
        dangerous:
          description: Tool poisoning, active prompt injection
          type: integer
        info:
          description: Low-severity CVEs, informational
          type: integer
        total:
          type: integer
        warning:
          description: Rug pull, supply chain CVEs with exploits
          type: integer
      type: object
    contracts.GetConfigResponse:
      properties:
        config:
          description: The configuration object
          type: object
        config_path:
          description: Path to config file
          type: string
      type: object
    contracts.GetRegistriesResponse:
      properties:
        registries:
          items:
            $ref: '#/components/schemas/contracts.Registry'
          type: array
          uniqueItems: false
        total:
          type: integer
      type: object
    contracts.GetServerLogsResponse:
      properties:
        count:
          type: integer
        logs:
          items:
            $ref: '#/components/schemas/contracts.LogEntry'
          type: array
          uniqueItems: false
        server_name:
          type: string
      type: object
    contracts.GetServerToolCallsResponse:
      properties:
        server_name:
          type: string
        tool_calls:
          items:
            $ref: '#/components/schemas/contracts.ToolCallRecord'
          type: array
          uniqueItems: false
        total:
          type: integer
      type: object
    contracts.GetServerToolsResponse:
      properties:
        count:
          type: integer
        server_name:
          type: string
        tools:
          items:
            $ref: '#/components/schemas/contracts.Tool'
          type: array
          uniqueItems: false
      type: object
    contracts.GetServersResponse:
      properties:
        servers:
          items:
            $ref: '#/components/schemas/contracts.Server'
          type: array
          uniqueItems: false
        stats:
          $ref: '#/components/schemas/contracts.ServerStats'
      type: object
    contracts.GetSessionDetailResponse:
      properties:
        session:
          $ref: '#/components/schemas/contracts.MCPSession'
      type: object
    contracts.GetSessionsResponse:
      properties:
        limit:
          type: integer
        offset:
          type: integer
        sessions:
          items:
            $ref: '#/components/schemas/contracts.MCPSession'
          type: array
          uniqueItems: false
        total:
          type: integer
      type: object
    contracts.GetToolCallDetailResponse:
      properties:
        tool_call:
          $ref: '#/components/schemas/contracts.ToolCallRecord'
      type: object
    contracts.GetToolCallsResponse:
      properties:
        limit:
          type: integer
        offset:
          type: integer
        tool_calls:
          items:
            $ref: '#/components/schemas/contracts.ToolCallRecord'
          type: array
          uniqueItems: false
        total:
          type: integer
      type: object
    contracts.GlobalToolsResponse:
      properties:
        failed_servers:
          items:
            type: string
          type: array
          uniqueItems: false
        partial:
          type: boolean
        stats:
          $ref: '#/components/schemas/contracts.GlobalToolsStats'
        tools:
          items:
            $ref: '#/components/schemas/contracts.Tool'
          type: array
          uniqueItems: false
      type: object
    contracts.GlobalToolsStats:
      properties:
        disabled:
          type: integer
        enabled:
          type: integer
        pending_approval:
          type: integer
        total:
          type: integer
      type: object
    contracts.HealthStatus:
      description: Unified health status calculated by the backend
      properties:
        action:
          description: 'Action is the suggested fix action: "login", "restart", "enable",
            "approve", "view_logs", "set_secret", "configure", or "" (none)'
          type: string
        admin_state:
          description: 'AdminState indicates the admin state: "enabled", "disabled",
            or "quarantined"'
          type: string
        detail:
          description: Detail is an optional longer explanation of the status
          type: string
        level:
          description: 'Level indicates the health level: "healthy", "degraded", or
            "unhealthy"'
          type: string
        summary:
          description: Summary is a human-readable status message (e.g., "Connected
            (5 tools)")
          type: string
      type: object
    contracts.InfoEndpoints:
      description: Available API endpoints
      properties:
        http:
          description: HTTP endpoint address (e.g., "127.0.0.1:8080")
          type: string
        socket:
          description: Unix socket path (empty if disabled)
          type: string
      type: object
    contracts.InfoResponse:
      properties:
        endpoints:
          $ref: '#/components/schemas/contracts.InfoEndpoints'
        listen_addr:
          description: Listen address (e.g., "127.0.0.1:8080")
          type: string
        update:
          $ref: '#/components/schemas/contracts.UpdateInfo'
        version:
          description: Current MCPProxy version
          type: string
        web_ui_url:
          description: URL to access the web control panel
          type: string
      type: object
    contracts.IsolationConfig:
      properties:
        cpu_limit:
          type: string
        enabled:
          type: boolean
        extra_args:
          items:
            type: string
          type: array
          uniqueItems: false
        image:
          type: string
        memory_limit:
          type: string
        network_mode:
          type: string
        timeout:
          type: string
        working_dir:
          type: string
      type: object
    contracts.IsolationDefaults:
      description: |-
        IsolationDefaults exposes the resolved baseline values that
        would apply when no per-server override is set. Populated on
        list/get responses; never consumed on PATCH requests.
      properties:
        extra_args:
          items:
            type: string
          type: array
          uniqueItems: false
        image:
          type: string
        network_mode:
          type: string
        runtime_type:
          type: string
        working_dir:
          type: string
      type: object
    contracts.LogEntry:
      properties:
        fields:
          type: object
        level:
          type: string
        message:
          type: string
        server:
          type: string
        timestamp:
          type: string
      type: object
    contracts.MCPSession:
      properties:
        client_name:
          type: string
        client_version:
          type: string
        end_time:
          type: string
        experimental:
          items:
            type: string
          type: array
          uniqueItems: false
        has_roots:
          description: MCP Client Capabilities
          type: boolean
        has_sampling:
          type: boolean
        id:
          type: string
        last_activity:
          type: string
        start_time:
          type: string
        status:
          type: string
        tool_call_count:
          type: integer
        total_tokens:
          type: integer
      type: object
    contracts.MetadataStatus:
      properties:
        authorization_servers:
          items:
            type: string
          type: array
          uniqueItems: false
        error:
          type: string
        found:
          type: boolean
        url_checked:
          type: string
      type: object
    contracts.MissingSecretInfo:
      properties:
        secret_name:
          type: string
        used_by:
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    contracts.NPMPackageInfo:
      properties:
        exists:
          type: boolean
        install_cmd:
          type: string
      type: object
    contracts.OAuthConfig:
      properties:
        auth_url:
          type: string
        client_id:
          type: string
        extra_params:
          additionalProperties:
            type: string
          type: object
        pkce_enabled:
          type: boolean
        redirect_port:
          type: integer
        scopes:
          items:
            type: string
          type: array
          uniqueItems: false
        token_expires_at:
          description: When the OAuth token expires
          type: string
        token_url:
          type: string
        token_valid:
          description: Whether token is currently valid
          type: boolean
      type: object
    contracts.OAuthErrorDetails:
      description: Structured discovery/failure details
      properties:
        authorization_server_metadata:
          $ref: '#/components/schemas/contracts.MetadataStatus'
        dcr_status:
          $ref: '#/components/schemas/contracts.DCRStatus'
        protected_resource_metadata:
          $ref: '#/components/schemas/contracts.MetadataStatus'
        server_url:
          type: string
      type: object
    contracts.OAuthFlowError:
      properties:
        correlation_id:
          description: Flow tracking ID for log correlation
          type: string
        debug_hint:
          description: CLI command for log lookup
          type: string
        details:
          $ref: '#/components/schemas/contracts.OAuthErrorDetails'
        error_code:
          description: Machine-readable error code (e.g., OAUTH_NO_METADATA)
          type: string
        error_type:
          description: Category of OAuth runtime failure
          type: string
        message:
          description: Human-readable error description
          type: string
        request_id:
          description: 'HTTP request ID (from PR #237)'
          type: string
        server_name:
          description: Server that failed OAuth
          type: string
        success:
          description: Always false
          type: boolean
        suggestion:
          description: Actionable remediation hint
          type: string
      type: object
    contracts.OAuthIssue:
      properties:
        documentation_url:
          type: string
        error:
          type: string
        issue:
          type: string
        missing_params:
          items:
            type: string
          type: array
          uniqueItems: false
        resolution:
          type: string
        server_name:
          type: string
      type: object
    contracts.OAuthRequirement:
      properties:
        expires_at:
          type: string
        message:
          type: string
        server_name:
          type: string
        state:
          type: string
      type: object
    contracts.OAuthStartResponse:
      properties:
        auth_url:
          description: Authorization URL (always included for manual use)
          type: string
        browser_error:
          description: Error message if browser launch failed
          type: string
        browser_opened:
          description: Whether browser launch succeeded
          type: boolean
        correlation_id:
          description: UUID for tracking this flow
          type: string
        message:
          description: Human-readable status message
          type: string
        server_name:
          description: Name of the server being authenticated
          type: string
        success:
          description: Always true for successful start
          type: boolean
      type: object
    contracts.QuarantineStats:
      description: Tool quarantine metrics for this server
      properties:
        blocked_count:
          description: Number of disabled (blocked) tools
          type: integer
        changed_count:
          description: Number of tools whose description/schema changed since approval
          type: integer
        pending_count:
          description: Number of newly discovered tools awaiting approval
          type: integer
      type: object
    contracts.Registry:
      properties:
        count:
          description: number or string
          type: string
        description:
          type: string
        id:
          type: string
        name:
          type: string
        protocol:
          type: string
        servers_url:
          type: string
        tags:
          items:
            type: string
          type: array
          uniqueItems: false
        url:
          type: string
      type: object
    contracts.ReplayToolCallRequest:
      properties:
        arguments:
          description: Modified arguments for replay
          type: object
      type: object
    contracts.ReplayToolCallResponse:
      properties:
        error:
          description: Error if replay failed
          type: string
        new_call_id:
          description: ID of the newly created call
          type: string
        new_tool_call:
          $ref: '#/components/schemas/contracts.ToolCallRecord'
        replayed_from:
          description: Original call ID
          type: string
        success:
          type: boolean
      type: object
    contracts.RepositoryInfo:
      description: Detected package info
      properties:
        npm:
          $ref: '#/components/schemas/contracts.NPMPackageInfo'
      type: object
    contracts.RepositoryServer:
      properties:
        connect_url:
          description: Alternative connection URL
          type: string
        created_at:
          type: string
        description:
          type: string
        id:
          type: string
        install_cmd:
          description: Installation command
          type: string
        name:
          type: string
        registry:
          description: Which registry this came from
          type: string
        repository_info:
          $ref: '#/components/schemas/contracts.RepositoryInfo'
        source_code_url:
          description: Source repository URL
          type: string
        updated_at:
          type: string
        url:
          description: MCP endpoint for remote servers only
          type: string
      type: object
    contracts.SearchRegistryServersResponse:
      properties:
        query:
          type: string
        registry_id:
          type: string
        servers:
          items:
            $ref: '#/components/schemas/contracts.RepositoryServer'
          type: array
          uniqueItems: false
        tag:
          type: string
        total:
          type: integer
      type: object
    contracts.SearchResult:
      properties:
        matches:
          type: integer
        score:
          type: number
        snippet:
          type: string
        tool:
          $ref: '#/components/schemas/contracts.Tool'
      type: object
    contracts.SearchToolsResponse:
      properties:
        query:
          type: string
        results:
          items:
            $ref: '#/components/schemas/contracts.SearchResult'
          type: array
          uniqueItems: false
        took:
          type: string
        total:
          type: integer
      type: object
    contracts.SecurityScanSummary:
      description: Latest security scan results summary
      properties:
        finding_counts:
          $ref: '#/components/schemas/contracts.FindingCounts'
        last_scan_at:
          type: string
        risk_score:
          description: 0-100
          type: integer
        status:
          description: '"clean", "warnings", "dangerous", "failed", "not_scanned",
            "scanning"'
          type: string
      type: object
    contracts.Server:
      properties:
        args:
          items:
            type: string
          type: array
          uniqueItems: false
        authenticated:
          description: OAuth authentication status
          type: boolean
        command:
          type: string
        connected:
          type: boolean
        connected_at:
          type: string
        connecting:
          type: boolean
        created:
          type: string
        diagnostic:
          $ref: '#/components/schemas/contracts.Diagnostic'
        enabled:
          type: boolean
        env:
          additionalProperties:
            type: string
          type: object
        error_code:
          type: string
        headers:
          additionalProperties:
            type: string
          type: object
        health:
          $ref: '#/components/schemas/contracts.HealthStatus'
        id:
          type: string
        isolation:
          $ref: '#/components/schemas/contracts.IsolationConfig'
        isolation_defaults:
          $ref: '#/components/schemas/contracts.IsolationDefaults'
        last_error:
          type: string
        last_reconnect_at:
          type: string
        last_retry_time:
          type: string
        name:
          type: string
        oauth:
          $ref: '#/components/schemas/contracts.OAuthConfig'
        oauth_status:
          description: 'OAuth status: "authenticated", "expired", "error", "none"'
          type: string
        protocol:
          type: string
        quarantine:
          $ref: '#/components/schemas/contracts.QuarantineStats'
        quarantined:
          type: boolean
        reconnect_count:
          type: integer
        reconnect_on_use:
          description: Attempt reconnection when a tool call targets this disconnected
            server
          type: boolean
        retry_count:
          type: integer
        security_scan:
          $ref: '#/components/schemas/contracts.SecurityScanSummary'
        should_retry:
          type: boolean
        status:
          type: string
        token_expires_at:
          description: When the OAuth token expires (ISO 8601)
          type: string
        tool_count:
          type: integer
        tool_list_token_size:
          description: Token size for this server's tools
          type: integer
        updated:
          type: string
        url:
          type: string
        user_logged_out:
          description: True if user explicitly logged out (prevents auto-reconnection)
          type: boolean
        working_dir:
          type: string
      type: object
    contracts.ServerActionResponse:
      properties:
        action:
          type: string
        async:
          type: boolean
        server:
          type: string
        success:
          type: boolean
      type: object
    contracts.ServerStats:
      properties:
        connected_servers:
          type: integer
        docker_containers:
          type: integer
        quarantined_servers:
          type: integer
        token_metrics:
          $ref: '#/components/schemas/contracts.ServerTokenMetrics'
        total_servers:
          type: integer
        total_tools:
          type: integer
      type: object
    contracts.ServerTokenMetrics:
      properties:
        average_query_result_size:
          description: Typical retrieve_tools output (tokens)
          type: integer
        per_server_tool_list_sizes:
          additionalProperties:
            type: integer
          description: Token size per server
          type: object
        saved_tokens:
          description: Difference
          type: integer
        saved_tokens_percentage:
          description: Percentage saved
          type: number
        total_server_tool_list_size:
          description: All upstream tools combined (tokens)
          type: integer
      type: object
    contracts.SuccessResponse:
      properties:
        data:
          type: object
        success:
          type: boolean
      type: object
    contracts.TokenMetrics:
      description: Token usage metrics (nil for older records)
      properties:
        encoding:
          description: Encoding used (e.g., cl100k_base)
          type: string
        estimated_cost:
          description: Optional cost estimate
          type: number
        input_tokens:
          description: Tokens in the request
          type: integer
        model:
          description: Model used for tokenization
          type: string
        output_tokens:
          description: Tokens in the response
          type: integer
        total_tokens:
          description: Total tokens (input + output)
          type: integer
        truncated_tokens:
          description: Tokens removed by truncation
          type: integer
        was_truncated:
          description: Whether response was truncated
          type: boolean
      type: object
    contracts.Tool:
      properties:
        annotations:
          $ref: '#/components/schemas/contracts.ToolAnnotation'
        approval_status:
          type: string
        config_denied:
          description: |-
            ConfigDenied is true when the tool is denied by the server's static
            enabled_tools / disabled_tools config. The user cannot override this toggle.
          type: boolean
        description:
          type: string
        disabled:
          description: |-
            Disabled mirrors ToolApprovalRecord.Disabled so per-tool enable state is
            available without a second round-trip to the approvals endpoint. Absent
            in the JSON when false (default) to keep responses compact.
          type: boolean
        last_used:
          type: string
        name:
          type: string
        schema:
          type: object
        server_name:
          type: string
        usage:
          type: integer
      type: object
    contracts.ToolAnnotation:
      description: Tool behavior hints snapshot
      properties:
        destructiveHint:
          type: boolean
        idempotentHint:
          type: boolean
        openWorldHint:
          type: boolean
        readOnlyHint:
          type: boolean
        title:
          type: string
      type: object
    contracts.ToolCallRecord:
      description: The new tool call record
      properties:
        annotations:
          $ref: '#/components/schemas/contracts.ToolAnnotation'
        arguments:
          description: Tool arguments
          type: object
        config_path:
          description: Active config file path
          type: string
        duration:
          description: Duration in nanoseconds
          type: integer
        error:
          description: Error message (failure only)
          type: string
        execution_type:
          description: '"direct" or "code_execution"'
          type: string
        id:
          description: Unique identifier
          type: string
        mcp_client_name:
          description: MCP client name from InitializeRequest
          type: string
        mcp_client_version:
          description: MCP client version
          type: string
        mcp_session_id:
          description: MCP session identifier
          type: string
        metrics:
          $ref: '#/components/schemas/contracts.TokenMetrics'
        parent_call_id:
          description: Links nested calls to parent code_execution
          type: string
        request_id:
          description: Request correlation ID
          type: string
        response:
          description: Tool response (success only)
          type: object
        server_id:
          description: Server identity hash
          type: string
        server_name:
          description: Human-readable server name
          type: string
        timestamp:
          description: When the call was made
          type: string
        tool_name:
          description: Tool name (without server prefix)
          type: string
      type: object
    contracts.UpdateInfo:
      description: Update information (if available)
      properties:
        available:
          description: Whether an update is available
          type: boolean
        check_error:
          description: Error message if update check failed
          type: string
        checked_at:
          description: When the update check was performed
          type: string
        is_prerelease:
          description: Whether the latest version is a prerelease
          type: boolean
        latest_version:
          description: Latest version available (e.g., "v1.2.3")
          type: string
        release_url:
          description: URL to the release page
          type: string
      type: object
    contracts.UpstreamError:
      properties:
        error_message:
          type: string
        server_name:
          type: string
        timestamp:
          type: string
      type: object
    contracts.ValidateConfigResponse:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/contracts.ValidationError'
          type: array
          uniqueItems: false
        valid:
          type: boolean
      type: object
    contracts.ValidationError:
      properties:
        field:
          type: string
        message:
          type: string
      type: object
    data:
      properties:
        data:
          $ref: '#/components/schemas/contracts.InfoResponse'
      type: object
    httpapi.AddServerRequest:
      properties:
        args:
          items:
            type: string
          type: array
          uniqueItems: false
        command:
          type: string
        enabled:
          type: boolean
        env:
          additionalProperties:
            type: string
          type: object
        headers:
          additionalProperties:
            type: string
          type: object
        isolation:
          $ref: '#/components/schemas/httpapi.IsolationRequest'
        name:
          type: string
        protocol:
          type: string
        quarantined:
          type: boolean
        reconnect_on_use:
          type: boolean
        url:
          type: string
        working_dir:
          type: string
      type: object
    httpapi.CanonicalConfigPath:
      properties:
        description:
          description: Brief description
          type: string
        exists:
          description: Whether the file exists
          type: boolean
        format:
          description: Format identifier (e.g., "claude_desktop")
          type: string
        name:
          description: Display name (e.g., "Claude Desktop")
          type: string
        os:
          description: Operating system (darwin, windows, linux)
          type: string
        path:
          description: Full path to the config file
          type: string
      type: object
    httpapi.CanonicalConfigPathsResponse:
      properties:
        os:
          description: Current operating system
          type: string
        paths:
          description: List of canonical config paths
          items:
            $ref: '#/components/schemas/httpapi.CanonicalConfigPath'
          type: array
          uniqueItems: false
      type: object
    httpapi.ConnectRequest:
      properties:
        force:
          description: Overwrite existing entry
          type: boolean
        server_name:
          description: Defaults to "mcpproxy"
          type: string
      type: object
    httpapi.ImportFromPathRequest:
      properties:
        format:
          description: Optional format hint
          type: string
        path:
          description: File path to import from
          type: string
        rename:
          additionalProperties:
            type: string
          description: |-
            Rename maps OriginalName → new name. Applied after parsing so the
            caller can disambiguate cross-source name collisions (Spec 046 v2 —
            e.g. "mcpproxy" → "mcpproxy_claude_code"). Keys not present in the
            imported set are ignored.
          type: object
        server_names:
          description: 'Optional: import only these servers'
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    httpapi.ImportRequest:
      properties:
        content:
          description: Raw JSON or TOML content
          type: string
        format:
          description: Optional format hint
          type: string
        server_names:
          description: 'Optional: import only these servers'
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    httpapi.ImportResponse:
      properties:
        failed:
          items:
            $ref: '#/components/schemas/configimport.FailedServer'
          type: array
          uniqueItems: false
        format:
          type: string
        format_name:
          type: string
        imported:
          items:
            $ref: '#/components/schemas/httpapi.ImportedServerResponse'
          type: array
          uniqueItems: false
        skipped:
          items:
            $ref: '#/components/schemas/configimport.SkippedServer'
          type: array
          uniqueItems: false
        summary:
          $ref: '#/components/schemas/configimport.ImportSummary'
        warnings:
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    httpapi.ImportedServerResponse:
      properties:
        args:
          items:
            type: string
          type: array
          uniqueItems: false
        command:
          type: string
        fields_skipped:
          items:
            type: string
          type: array
          uniqueItems: false
        name:
          type: string
        original_name:
          type: string
        protocol:
          type: string
        source_format:
          type: string
        url:
          type: string
        warnings:
          items:
            type: string
          type: array
          uniqueItems: false
      type: object
    httpapi.IsolationRequest:
      description: |-
        Isolation carries per-server Docker isolation overrides (image,
        network_mode, extra_args, working_dir, enabled). A nil pointer
        means "do not touch isolation config"; an empty-but-present
        object on PATCH intentionally clears the overrides.
      properties:
        enabled:
          type: boolean
        extra_args:
          items:
            type: string
          type: array
          uniqueItems: false
        image:
          type: string
        network_mode:
          type: string
        working_dir:
          type: string
      type: object
    httpapi.OnboardingMarkRequest:
      properties:
        connect_step_status:
          description: |-
            ConnectStepStatus is one of: "", "completed", "skipped". Empty
            preserves the existing value.
          type: string
        engaged:
          description: |-
            Engaged marks the wizard as engaged (completed or explicitly skipped).
            Once true, the wizard does not auto-show again.
          type: boolean
        mark_shown:
          description: MarkShown records the wizard's first display time if not already
            set.
          type: boolean
        server_step_status:
          description: |-
            ServerStepStatus is one of: "", "completed", "skipped". Empty
            preserves the existing value.
          type: string
      type: object
    management.BulkOperationResult:
      properties:
        errors:
          additionalProperties:
            type: string
          description: Map of server name to error message
          type: object
        failed:
          description: Number of failed operations
          type: integer
        successful:
          description: Number of successful operations
          type: integer
        total:
          description: Total servers processed
          type: integer
      type: object
    observability.HealthResponse:
      properties:
        components:
          items:
            $ref: '#/components/schemas/observability.HealthStatus'
          type: array
          uniqueItems: false
        status:
          description: '"healthy" or "unhealthy"'
          type: string
        timestamp:
          type: string
      type: object
    observability.HealthStatus:
      properties:
        error:
          type: string
        latency:
          type: string
        name:
          type: string
        status:
          description: '"healthy" or "unhealthy"'
          type: string
      type: object
    observability.ReadinessResponse:
      properties:
        components:
          items:
            $ref: '#/components/schemas/observability.HealthStatus'
          type: array
          uniqueItems: false
        status:
          description: '"ready" or "not_ready"'
          type: string
        timestamp:
          type: string
      type: object
    secureenv.EnvConfig:
      description: Environment configuration for secure variable filtering
      properties:
        allowed_system_vars:
          items:
            type: string
          type: array
          uniqueItems: false
        custom_vars:
          additionalProperties:
            type: string
          type: object
        enhance_path:
          description: Enable PATH enhancement for Launchd scenarios
          type: boolean
        inherit_system_safe:
          type: boolean
      type: object
    telemetry.FeedbackContext:
      properties:
        arch:
          type: string
        connected_server_count:
          type: integer
        edition:
          type: string
        os:
          type: string
        routing_mode:
          type: string
        server_count:
          type: integer
        version:
          type: string
      type: object
    telemetry.FeedbackRequest:
      properties:
        category:
          description: bug, feature, other
          type: string
        context:
          $ref: '#/components/schemas/telemetry.FeedbackContext'
        email:
          type: string
        message:
          type: string
      type: object
    telemetry.FeedbackResponse:
      properties:
        error:
          type: string
        issue_url:
          type: string
        success:
          type: boolean
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: API key authentication via query parameter. Use ?apikey=your-key
      in: query
      name: apikey
      type: apiKey
externalDocs:
  description: ""
  url: ""
info:
  contact:
    name: MCPProxy Support
    url: https://github.com/smart-mcp-proxy/mcpproxy-go
  description: |-
    MCPProxy REST API for managing MCP servers, tools, and diagnostics

    MCPProxy is a smart proxy for AI agents using the Model Context Protocol (MCP).
    It provides intelligent tool discovery, massive token savings, and built-in security quarantine.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  title: MCPProxy API
  version: "1.0"
openapi: 3.1.0
paths:
  /api/v1/activity:
    get:
      description: Returns paginated list of activity records with optional filtering
      parameters:
      - description: Filter by activity type(s), comma-separated for multiple (Spec
          024)
        in: query
        name: type
        schema:
          enum:
          - tool_call
          - policy_decision
          - quarantine_change
          - server_change
          - system_start
          - system_stop
          - internal_tool_call
          - config_change
          type: string
      - description: Filter by server name
        in: query
        name: server
        schema:
          type: string
      - description: Filter by tool name
        in: query
        name: tool
        schema:
          type: string
      - description: Filter by MCP session ID
        in: query
        name: session_id
        schema:
          type: string
      - description: Filter by status
        in: query
        name: status
        schema:
          enum:
          - success
          - error
          - blocked
          type: string
      - description: Filter by intent operation type (Spec 018)
        in: query
        name: intent_type
        schema:
          enum:
          - read
          - write
          - destructive
          type: string
      - description: Filter by HTTP request ID for log correlation (Spec 021)
        in: query
        name: request_id
        schema:
          type: string
      - description: 'Include successful call_tool_* internal tool calls (default:
          false, excluded to avoid duplicates)'
        in: query
        name: include_call_tool
        schema:
          type: boolean
      - description: Filter by sensitive data detection (true=has detections, false=no
          detections)
        in: query
        name: sensitive_data
        schema:
          type: boolean
      - description: Filter by specific detection type (e.g., 'aws_access_key', 'credit_card')
        in: query
        name: detection_type
        schema:
          type: string
      - description: Filter by severity level
        in: query
        name: severity
        schema:
          enum:
          - critical
          - high
          - medium
          - low
          type: string
      - description: Filter by agent token name (Spec 028)
        in: query
        name: agent
        schema:
          type: string
      - description: Filter by auth type (Spec 028)
        in: query
        name: auth_type
        schema:
          enum:
          - admin
          - agent
          type: string
      - description: Filter activities after this time (RFC3339)
        in: query
        name: start_time
        schema:
          type: string
      - description: Filter activities before this time (RFC3339)
        in: query
        name: end_time
        schema:
          type: string
      - description: Maximum records to return (1-100, default 50)
        in: query
        name: limit
        schema:
          type: integer
      - description: Pagination offset (default 0)
        in: query
        name: offset
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/data'
                properties:
                  data:
                    type: object
                  error:
                    type: string
                  request_id:
                    type: string
                  success:
                    type: boolean
                type: object
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.APIResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.APIResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.APIResponse'
          description: Internal Server Error
      security:
      - ApiKeyHeader: []
      - ApiKeyQuery: []
      summary: List activity records
      tags:
      - Activity
  /api/v1/activity/{id}:
    get:
      description: Returns full details for a single activity record
      parameters:
      - description: Activity record ID (ULID)
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/data'
                properties:
                  data:
                    type: object
                  error:
                    type: string
                  request_id:
                    type: string
                  success:
                    type: boolean
                type: object
          description: OK
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.APIResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.APIResponse'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.APIResponse'
          description: Internal Server Error
      security:
      - ApiKeyHeader: []
      - ApiKeyQuery: []
      summary: Get activity record details
      tags:
      - Activity
  /api/v1/activity/export:
    get:
      description: Exports activity records in JSON Lines or CSV format for compliance
      parameters:
      - description: 'Export format: json (default) or csv'
        in: query
        name: format
        schema:
          type: string
      - description: Filter by activity type
        in: query
        name: type
        schema:
          type: string
      - description: Filter by server name
        in: query
        name: server
        schema:
          type: string
      - description: Filter by tool name
        in: query
        name: tool
        schema:
          type: string
      - description: Filter by MCP session ID
        in: query
        name: session_id
        schema:
          type: string
      - description: Filter by status
        in: query
        name: status
        schema:
          type: string
      - description: Filter activities after this time (RFC3339)
        in: query
        name: start_time
        schema:
          type: string
      - description: Filter activities before this time (RFC3339)
        in: query
        name: end_time
        schema:
          type: string
      - description: Maximum records to export (1-50000, default 10000)
        in: query
        name: limit
        schema:
          type: integer
      - description: Pagination offset (default 0)
        in: query
        name: offset
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                type: string
            application/x-ndjson:
              schema:
                type: string
            text/csv:
              schema:
                type: string
          description: Streamed activity records
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.APIResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.APIResponse'
          description: Internal Server Error
      security:
      - ApiKeyHeader: []
      - ApiKeyQuery: []
      summary: Export activity records
      tags:
      - Activity
  /api/v1/activity/summary:
    get:
      description: Returns aggregated activity statistics for a time period
      parameters:
      - description: 'Time period: 1h, 24h (default), 7d, 30d'
        in: query
        name: period
        schema:
          type: string
      - description: 'Group by: server, tool (optional)'
        in: query
        name: group_by
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/data'
                properties:
                  data:
                    type: object
                  error:
                    type: string
                  request_id:
                    type: string
                  success:
                    type: boolean
                type: object
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.APIResponse'
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.APIResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.APIResponse'
          description: Internal Server Error
      security:
      - ApiKeyHeader: []
      - ApiKeyQuery: []
      summary: Get activity summary statistics
      tags:
      - Activity
  /api/v1/annotations/coverage:
    get:
      description: Reports how many upstream tools have MCP annotations vs don't,
        broken down by server
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.SuccessResponse'
          description: Annotation coverage report
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Get annotation coverage report
      tags:
      - annotations
  /api/v1/config:
    get:
      description: Retrieves the current MCPProxy configuration including all server
        definitions, global settings, and runtime parameters
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.GetConfigResponse'
          description: Configuration retrieved successfully
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Unauthorized - missing or invalid API key
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Failed to get configuration
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Get current configuration
      tags:
      - config
  /api/v1/config/apply:
    post:
      description: Applies a new MCPProxy configuration. Validates and persists the
        configuration to disk. Some changes apply immediately, while others may require
        a restart. Returns detailed information about applied changes and restart
        requirements.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/config.Config'
        description: Configuration to apply
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ConfigApplyResult'
          description: Configuration applied successfully with change details
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Invalid JSON payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Unauthorized - missing or invalid API key
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Failed to apply configuration
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Apply configuration
      tags:
      - config
  /api/v1/config/docker-isolation:
    patch:
      description: Convenience endpoint to flip `docker_isolation.enabled` without
        resending the full config. Persists to disk via the existing config writer
        — the file watcher then hot-reloads the change. Returns the new state and
        whether a restart is required for existing connections to pick it up.
      requestBody:
        content:
          application/json:
            schema:
              properties:
                enabled:
                  type: boolean
              type: object
        description: New isolation state
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ConfigApplyResult'
          description: Isolation toggle applied
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Invalid JSON payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Unauthorized - missing or invalid API key
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Failed to apply configuration
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Toggle global Docker isolation
      tags:
      - config
  /api/v1/config/validate:
    post:
      description: Validates a provided MCPProxy configuration without applying it.
        Checks for syntax errors, invalid server definitions, conflicting settings,
        and other configuration issues.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/config.Config'
        description: Configuration to validate
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ValidateConfigResponse'
          description: Configuration validation result
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Invalid JSON payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Unauthorized - missing or invalid API key
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Validation failed
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Validate configuration
      tags:
      - config
  /api/v1/connect:
    get:
      description: |-
        Returns the connection status for all known MCP client applications.
        Each entry indicates whether the client config file exists and whether
        MCPProxy is currently registered in it.
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.APIResponse'
          description: List of ClientStatus objects
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: List client connection status
      tags:
      - connect
  /api/v1/connect/{client}:
    delete:
      description: |-
        Remove the MCPProxy entry from the specified client's configuration file.
        Creates a backup of the existing config before modifying.
      parameters:
      - description: Client ID (claude-code, cursor, windsurf, vscode, codex, gemini)
        in: path
        name: client
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/httpapi.ConnectRequest'
        description: Optional parameters (server_name)
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.APIResponse'
          description: ConnectResult
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Unknown client or entry not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Service unavailable
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Disconnect MCPProxy from a client
      tags:
      - connect
    post:
      description: |-
        Register MCPProxy as an MCP server in the specified client's configuration file.
        Creates a backup of the existing config before modifying.
      parameters:
      - description: Client ID (claude-code, cursor, windsurf, vscode, codex, gemini)
        in: path
        name: client
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/httpapi.ConnectRequest'
        description: Optional connection parameters
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.APIResponse'
          description: ConnectResult
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Unknown client
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Already connected (use force=true)
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Service unavailable
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Connect MCPProxy to a client
      tags:
      - connect
  /api/v1/diagnostics:
    get:
      description: Get comprehensive health diagnostics including upstream errors,
        OAuth requirements, missing secrets, and Docker status
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.Diagnostics'
          description: Health diagnostics
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Get health diagnostics
      tags:
      - diagnostics
  /api/v1/docker/status:
    get:
      description: Retrieve current Docker availability and recovery status
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.SuccessResponse'
          description: Docker status information
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Get Docker status
      tags:
      - docker
  /api/v1/doctor:
    get:
      description: Get comprehensive health diagnostics including upstream errors,
        OAuth requirements, missing secrets, and Docker status
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.Diagnostics'
          description: Health diagnostics
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Get health diagnostics
      tags:
      - diagnostics
  /api/v1/feedback:
    post:
      description: Submit a bug report, feature request, or general feedback
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/telemetry.FeedbackRequest'
        description: Feedback request
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/telemetry.FeedbackResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad Request
        "429":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Too Many Requests
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      summary: Submit feedback
      tags:
      - feedback
  /api/v1/index/search:
    get:
      description: Search across all upstream MCP server tools using BM25 keyword
        search
      parameters:
      - description: Search query
        in: query
        name: q
        required: true
        schema:
          type: string
      - description: Maximum number of results
        in: query
        name: limit
        schema:
          default: 10
          maximum: 100
          type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.SearchToolsResponse'
          description: Search results
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request (missing query parameter)
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Search for tools
      tags:
      - tools
  /api/v1/info:
    get:
      description: |-
        Get essential server metadata including version, web UI URL, endpoint addresses, and update availability
        This endpoint is designed for tray-core communication and version checking
        Use refresh=true query parameter to force an immediate update check against GitHub
      parameters:
      - description: Force immediate update check against GitHub
        in: query
        name: refresh
        schema:
          type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/data'
                properties:
                  data:
                    type: object
                  error:
                    type: string
                  request_id:
                    type: string
                  success:
                    type: boolean
                type: object
          description: Server information with optional update info
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Get server information
      tags:
      - status
  /api/v1/onboarding/mark:
    post:
      description: |-
        Updates wizard engagement and per-step status. Once engaged is
        true, the wizard does not auto-show again, even if state regresses.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/httpapi.OnboardingMarkRequest'
        description: Mark request
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.APIResponse'
          description: Updated OnboardingStateResponse
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Service unavailable
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Mark onboarding wizard state (Spec 046)
      tags:
      - onboarding
  /api/v1/onboarding/state:
    get:
      description: |-
        Returns the wizard engagement record alongside live predicates
        (whether any client is connected, whether any server is configured),
        plus a derived ShouldShowWizard flag the frontend can rely on.
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.APIResponse'
          description: OnboardingStateResponse
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Service unavailable
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Get onboarding wizard state and predicates (Spec 046)
      tags:
      - onboarding
  /api/v1/registries:
    get:
      description: Retrieves list of all MCP server registries that can be browsed
        for discovering and installing new upstream servers. Includes registry metadata,
        server counts, and API endpoints.
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.GetRegistriesResponse'
          description: Registries retrieved successfully
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Unauthorized - missing or invalid API key
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Failed to list registries
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: List available MCP server registries
      tags:
      - registries
  /api/v1/registries/{id}/servers:
    get:
      description: Searches for MCP servers within a specific registry by keyword
        or tag. Returns server metadata including installation commands, source code
        URLs, and npm package information for easy discovery and installation.
      parameters:
      - description: Registry ID
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Search query keyword
        in: query
        name: q
        schema:
          type: string
      - description: Filter by tag
        in: query
        name: tag
        schema:
          type: string
      - description: Maximum number of results (default 10)
        in: query
        name: limit
        schema:
          type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.SearchRegistryServersResponse'
          description: Servers retrieved successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Registry ID required
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Unauthorized - missing or invalid API key
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Failed to search servers
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Search MCP servers in a registry
      tags:
      - registries
  /api/v1/routing:
    get:
      description: Get the current routing mode and available MCP endpoints
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.SuccessResponse'
          description: Routing mode information
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Get routing mode information
      tags:
      - status
  /api/v1/secrets:
    post:
      description: Stores a secret value in the operating system's secure keyring.
        The secret can then be referenced in configuration using ${keyring:secret-name}
        syntax. Automatically notifies runtime to restart affected servers.
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: {}
                type: object
          description: Secret stored successfully with reference syntax
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Invalid JSON payload, missing name/value, or unsupported type
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Unauthorized - missing or invalid API key
        "405":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Method not allowed
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Secret resolver not available or failed to store secret
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Store a secret in OS keyring
      tags:
      - secrets
  /api/v1/secrets/{name}:
    delete:
      description: Deletes a secret from the operating system's secure keyring. Automatically
        notifies runtime to restart affected servers. Only keyring type is supported
        for security.
      parameters:
      - description: Name of the secret to delete
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Secret type (only 'keyring' supported, defaults to 'keyring')
        in: query
        name: type
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: {}
                type: object
          description: Secret deleted successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Missing secret name or unsupported type
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Unauthorized - missing or invalid API key
        "405":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Method not allowed
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Secret resolver not available or failed to delete secret
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Delete a secret from OS keyring
      tags:
      - secrets
  /api/v1/servers:
    get:
      description: Get a list of all configured upstream MCP servers with their connection
        status and statistics
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.GetServersResponse'
          description: Server list with statistics
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: List all upstream MCP servers
      tags:
      - servers
    post:
      description: Add a new MCP upstream server to the configuration. New servers
        are quarantined by default for security.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/httpapi.AddServerRequest'
        description: Server configuration
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ServerActionResponse'
          description: Server added successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request - invalid configuration
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Conflict - server with this name already exists
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Add a new upstream server
      tags:
      - servers
  /api/v1/servers/{id}:
    delete:
      description: Remove an MCP upstream server from the configuration. This stops
        the server if running and removes it from config.
      parameters:
      - description: Server ID or name
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ServerActionResponse'
          description: Server removed successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Server not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Remove an upstream server
      tags:
      - servers
    patch:
      description: Update specific fields of an existing upstream MCP server configuration.
      parameters:
      - description: Server ID or name
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/httpapi.AddServerRequest'
        description: Fields to update (all optional)
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.SuccessResponse'
          description: Server updated successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request - no fields or invalid body
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Server not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Partially update an upstream server
      tags:
      - servers
  /api/v1/servers/{id}/config-to-secret:
    post:
      description: Atomically reads the real value from the server config, stores
        it in the OS keyring, and rewrites the config field to `${keyring:<name>}`.
        Unblocks the UI's Convert-to-secret affordance for values the API redacts
        on the read path.
      parameters:
      - description: Server ID or name
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: {}
                type: object
          description: Secret stored, config updated with reference
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad scope/key/secret_name, or value is already a reference
            / empty
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Server or key not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Secret resolver or config update failed
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Convert a header / env value to a keyring secret
      tags:
      - servers
  /api/v1/servers/{id}/disable:
    post:
      description: Disable a specific upstream MCP server
      parameters:
      - description: Server ID or name
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ServerActionResponse'
          description: Server disabled successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Server not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Disable an upstream server
      tags:
      - servers
  /api/v1/servers/{id}/discover-tools:
    post:
      description: Manually trigger tool discovery and indexing for a specific upstream
        MCP server. This forces an immediate refresh of the server's tool cache.
      parameters:
      - description: Server ID or name
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ServerActionResponse'
          description: Tool discovery triggered successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request (missing server ID)
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Server not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Failed to discover tools
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Discover tools for a specific server
      tags:
      - servers
  /api/v1/servers/{id}/enable:
    post:
      description: Enable a specific upstream MCP server
      parameters:
      - description: Server ID or name
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ServerActionResponse'
          description: Server enabled successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Server not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Enable an upstream server
      tags:
      - servers
  /api/v1/servers/{id}/login:
    post:
      description: Initiate OAuth authentication flow for a specific upstream MCP
        server. Returns structured OAuth start response with correlation ID for tracking.
      parameters:
      - description: Server ID or name
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.OAuthStartResponse'
          description: OAuth login initiated successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.OAuthFlowError'
          description: OAuth error (client_id required, DCR failed, etc.)
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Server not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Trigger OAuth login for server
      tags:
      - servers
  /api/v1/servers/{id}/logout:
    post:
      description: Clear OAuth authentication token and disconnect a specific upstream
        MCP server. The server will need to re-authenticate before tools can be used
        again.
      parameters:
      - description: Server ID or name
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ServerActionResponse'
          description: OAuth logout completed successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request (missing server ID)
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Forbidden (management disabled or read-only mode)
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Server not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Clear OAuth token and disconnect server
      tags:
      - servers
  /api/v1/servers/{id}/logs:
    get:
      description: Retrieve log entries for a specific upstream MCP server
      parameters:
      - description: Server ID or name
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Number of log lines to retrieve
        in: query
        name: tail
        schema:
          default: 100
          type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.GetServerLogsResponse'
          description: Server logs retrieved successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request (missing server ID)
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Server not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Get server logs
      tags:
      - servers
  /api/v1/servers/{id}/quarantine:
    post:
      description: Place a specific upstream MCP server in quarantine to prevent tool
        execution
      parameters:
      - description: Server ID or name
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ServerActionResponse'
          description: Server quarantined successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request (missing server ID)
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Server not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Quarantine a server
      tags:
      - servers
  /api/v1/servers/{id}/restart:
    post:
      description: Restart the connection to a specific upstream MCP server
      parameters:
      - description: Server ID or name
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ServerActionResponse'
          description: Server restarted successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Server not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Restart an upstream server
      tags:
      - servers
  /api/v1/servers/{id}/tool-calls:
    get:
      description: Retrieves tool call history filtered by upstream server ID. Returns
        recent tool executions for the specified server including timestamps, arguments,
        results, and errors. Useful for server-specific debugging and monitoring.
      parameters:
      - description: Upstream server ID or name
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Maximum number of records to return (1-100, default 50)
        in: query
        name: limit
        schema:
          type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.GetServerToolCallsResponse'
          description: Server tool calls retrieved successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Server ID required
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Unauthorized - missing or invalid API key
        "405":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Method not allowed
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Failed to get server tool calls
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Get tool call history for specific server
      tags:
      - tool-calls
  /api/v1/servers/{id}/tools:
    get:
      description: Retrieve all available tools for a specific upstream MCP server
      parameters:
      - description: Server ID or name
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.GetServerToolsResponse'
          description: Server tools retrieved successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request (missing server ID)
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Server not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Get tools for a server
      tags:
      - servers
  /api/v1/servers/{id}/tools/disable_all:
    post:
      description: Bulk-toggles every known tool of a server. The "changed" field
      parameters:
      - description: Server ID or name
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.SuccessResponse'
          description: Operation result
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Enable or disable all tools for a server
      tags:
      - servers
  /api/v1/servers/{id}/tools/enable_all:
    post:
      description: Bulk-toggles every known tool of a server. The "changed" field
      parameters:
      - description: Server ID or name
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.SuccessResponse'
          description: Operation result
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Enable or disable all tools for a server
      tags:
      - servers
  /api/v1/servers/{id}/unquarantine:
    post:
      description: Remove a specific upstream MCP server from quarantine to allow
        tool execution
      parameters:
      - description: Server ID or name
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ServerActionResponse'
          description: Server unquarantined successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request (missing server ID)
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Server not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Unquarantine a server
      tags:
      - servers
  /api/v1/servers/disable_all:
    post:
      description: Disable all configured upstream MCP servers with partial failure
        handling
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/management.BulkOperationResult'
          description: Bulk disable results with success/failure counts
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Forbidden (management disabled)
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Disable all servers
      tags:
      - servers
  /api/v1/servers/enable_all:
    post:
      description: Enable all configured upstream MCP servers with partial failure
        handling
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/management.BulkOperationResult'
          description: Bulk enable results with success/failure counts
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Forbidden (management disabled)
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Enable all servers
      tags:
      - servers
  /api/v1/servers/import:
    post:
      description: Import MCP server configurations from a Claude Desktop, Claude
        Code, Cursor IDE, Codex CLI, or Gemini CLI configuration file
      parameters:
      - description: If true, return preview without importing
        in: query
        name: preview
        schema:
          type: boolean
      - description: Force format (claude-desktop, claude-code, cursor, codex, gemini)
        in: query
        name: format
        schema:
          type: string
      - description: Comma-separated list of server names to import
        in: query
        name: server_names
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: file
        description: Configuration file to import
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpapi.ImportResponse'
          description: Import result
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request - invalid file or format
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Import servers from uploaded configuration file
      tags:
      - servers
  /api/v1/servers/import/json:
    post:
      description: Import MCP server configurations from raw JSON or TOML content
        (useful for pasting configurations)
      parameters:
      - description: If true, return preview without importing
        in: query
        name: preview
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/httpapi.ImportRequest'
        description: Import request with content
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpapi.ImportResponse'
          description: Import result
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request - invalid content or format
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Import servers from JSON/TOML content
      tags:
      - servers
  /api/v1/servers/import/path:
    post:
      description: Import MCP server configurations by reading a file from the server's
        filesystem
      parameters:
      - description: If true, return preview without importing
        in: query
        name: preview
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/httpapi.ImportFromPathRequest'
        description: Import request with file path
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpapi.ImportResponse'
          description: Import result
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request - invalid path or format
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: File not found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Import servers from a file path
      tags:
      - servers
  /api/v1/servers/import/paths:
    get:
      description: Returns well-known configuration file paths for supported formats
        with existence check
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpapi.CanonicalConfigPathsResponse'
          description: Canonical config paths
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Get canonical config file paths
      tags:
      - servers
  /api/v1/servers/reconnect:
    post:
      description: Force reconnection to all upstream MCP servers
      parameters:
      - description: Reason for reconnection
        in: query
        name: reason
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ServerActionResponse'
          description: All servers reconnected successfully
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Reconnect all servers
      tags:
      - servers
  /api/v1/servers/restart_all:
    post:
      description: Restart all configured upstream MCP servers sequentially with partial
        failure handling
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/management.BulkOperationResult'
          description: Bulk restart results with success/failure counts
        "403":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Forbidden (management disabled)
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Restart all servers
      tags:
      - servers
  /api/v1/sessions:
    get:
      description: Retrieves paginated list of active and recent MCP client sessions.
        Each session represents a connection from an MCP client to MCPProxy, tracking
        initialization time, tool calls, and connection status.
      parameters:
      - description: Maximum number of sessions to return (1-100, default 10)
        in: query
        name: limit
        schema:
          type: integer
      - description: Number of sessions to skip for pagination (default 0)
        in: query
        name: offset
        schema:
          type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.GetSessionsResponse'
          description: Sessions retrieved successfully
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Unauthorized - missing or invalid API key
        "405":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Method not allowed
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Failed to get sessions
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Get active MCP sessions
      tags:
      - sessions
  /api/v1/sessions/{id}:
    get:
      description: Retrieves detailed information about a specific MCP client session
        including initialization parameters, connection status, tool call count, and
        activity timestamps.
      parameters:
      - description: Session ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.GetSessionDetailResponse'
          description: Session details retrieved successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Session ID required
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Unauthorized - missing or invalid API key
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Session not found
        "405":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Method not allowed
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Get MCP session details by ID
      tags:
      - sessions
  /api/v1/stats/tokens:
    get:
      description: Retrieve token savings statistics across all servers and sessions
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.SuccessResponse'
          description: Token statistics
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Get token savings statistics
      tags:
      - stats
  /api/v1/status:
    get:
      description: Get comprehensive server status including running state, listen
        address, upstream statistics, and timestamp
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.SuccessResponse'
          description: Server status information
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Get server status
      tags:
      - status
  /api/v1/telemetry/payload:
    get:
      description: Render the exact JSON heartbeat payload that mcpproxy would next
        send to the telemetry endpoint, without making a network call. Counters in
        the payload reflect the current in-memory state. Spec 042.
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.SuccessResponse'
          description: Telemetry heartbeat payload
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Telemetry service unavailable
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Preview next telemetry heartbeat payload
      tags:
      - telemetry
  /api/v1/tool-calls:
    get:
      description: Retrieves paginated tool call history across all upstream servers
        or filtered by session ID. Includes execution timestamps, arguments, results,
        and error information for debugging and auditing.
      parameters:
      - description: Maximum number of records to return (1-100, default 50)
        in: query
        name: limit
        schema:
          type: integer
      - description: Number of records to skip for pagination (default 0)
        in: query
        name: offset
        schema:
          type: integer
      - description: Filter tool calls by MCP session ID
        in: query
        name: session_id
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.GetToolCallsResponse'
          description: Tool calls retrieved successfully
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Unauthorized - missing or invalid API key
        "405":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Method not allowed
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Failed to get tool calls
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Get tool call history
      tags:
      - tool-calls
  /api/v1/tool-calls/{id}:
    get:
      description: Retrieves detailed information about a specific tool call execution
        including full request arguments, response data, execution time, and any errors
        encountered.
      parameters:
      - description: Tool call ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.GetToolCallDetailResponse'
          description: Tool call details retrieved successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Tool call ID required
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Unauthorized - missing or invalid API key
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Tool call not found
        "405":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Method not allowed
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Get tool call details by ID
      tags:
      - tool-calls
  /api/v1/tool-calls/{id}/replay:
    post:
      description: Re-executes a previous tool call with optional modified arguments.
        Useful for debugging and testing tool behavior with different inputs. Creates
        a new tool call record linked to the original.
      parameters:
      - description: Original tool call ID to replay
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/contracts.ReplayToolCallRequest'
        description: Optional modified arguments for replay
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ReplayToolCallResponse'
          description: Tool call replayed successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Tool call ID required or invalid JSON payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Unauthorized - missing or invalid API key
        "405":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Method not allowed
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Failed to replay tool call
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Replay a tool call
      tags:
      - tool-calls
  /api/v1/tools:
    get:
      description: 'Consolidated, read-only listing of all tools from every configured
        server (including disabled servers and disabled/config-denied tools), enriched
        with approval state and 30-day usage. Backs the global Tools page and the
        CLI global `tools list` (spec 050, issue #437).'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.GlobalToolsResponse'
          description: All tools across all servers
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Could not enumerate servers
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: List every tool across all servers
      tags:
      - tools
  /api/v1/tools/call:
    post:
      description: Execute a tool on an upstream MCP server (wrapper around MCP tool
        calls)
      requestBody:
        content:
          application/json:
            schema:
              properties:
                arguments:
                  type: object
                tool_name:
                  type: string
              type: object
        description: Tool call request with tool name and arguments
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.SuccessResponse'
          description: Tool call result
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Bad request (invalid payload or missing tool name)
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contracts.ErrorResponse'
          description: Internal server error or tool execution failure
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      summary: Call a tool
      tags:
      - tools
  /healthz:
    get:
      description: Get comprehensive health status including all component health
        (Kubernetes-compatible liveness probe)
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/observability.HealthResponse'
          description: Service is healthy
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/observability.HealthResponse'
          description: Service is unhealthy
      summary: Get health status
      tags:
      - health
  /readyz:
    get:
      description: Get readiness status including all component readiness checks (Kubernetes-compatible
        readiness probe)
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/observability.ReadinessResponse'
          description: Service is ready
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/observability.ReadinessResponse'
          description: Service is not ready
      summary: Get readiness status
      tags:
      - health
