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: 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' mcpServers: items: $ref: '#/components/schemas/config.ServerConfig' type: array uniqueItems: false oauth_expiry_warning_hours: description: Health status settings type: number read_only_mode: type: boolean registries: description: Registries configuration for MCP server discovery items: $ref: '#/components/schemas/config.RegistryEntry' type: array uniqueItems: false sensitive_data_detection: $ref: '#/components/schemas/config.SensitiveDataDetectionConfig' tls: $ref: '#/components/schemas/config.TLSConfig' tokenizer: $ref: '#/components/schemas/config.TokenizerConfig' tool_response_limit: type: integer tools_limit: type: integer top_k: 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 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: Feature flags for modular functionality 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.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 enabled: type: boolean env: additionalProperties: type: string type: object headers: additionalProperties: type: string description: For HTTP servers type: object isolation: $ref: '#/components/schemas/config.IsolationConfig' 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 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.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.Diagnostics: properties: 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.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.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 image: type: string memory_limit: type: string timeout: 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.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.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 enabled: type: boolean env: additionalProperties: type: string type: object headers: additionalProperties: type: string type: object health: $ref: '#/components/schemas/contracts.HealthStatus' id: type: string isolation: $ref: '#/components/schemas/contracts.IsolationConfig' 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 quarantined: type: boolean reconnect_count: type: integer retry_count: type: integer 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' description: type: string 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 name: type: string protocol: type: string quarantined: 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.ImportFromPathRequest: properties: format: description: Optional format hint type: string path: description: File path to import from type: string 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 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 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 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 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/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/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/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/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/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/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 /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}/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/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/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