Hangar MCP

Approve a pending or quarantined mcp_server for registration.

CHOOSE THIS when: ready to register a mcp_server from pending or quarantine list. CHOOSE hangar_discovered when: you need to review pending mcp_servers first. CHOOSE hangar_quarantine when: you need to see why a mcp_server was quarantined.

Side effects: Registers the mcp_server in cold state. Removes from pending/quarantine.

Args: mcp_server: str - McpServer name (from hangar_discovered or hangar_quarantine output)

Returns: Success: {approved: true, mcp_server: str, status: "registered"} Not found: {approved: false, mcp_server: str, error: str} Not configured: {error: str}

Example: hangar_approve("my-new-mcp_server") # {"approved": true, "mcp_server": "my-new-mcp_server", "status": "registered"}

hangar_approve("unknown") # {"approved": false, "mcp_server": "unknown", "error": "McpServer not found in quarantine"}

hangar_approve("x") # when not configured # {"error": "Discovery not configured. Enable discovery in config.yaml"}

Invoke tools on MCP mcp_servers (single or batch).

CHOOSE THIS when: you want to execute tool(s) on mcp_server(s). This is the main entry point. CHOOSE hangar_tools when: you need to discover available tools before calling. CHOOSE hangar_start when: you only want to pre-warm without invoking.

Side effects: May start cold mcp_servers. Executes calls in parallel.

Concurrency model: Two levels of concurrency control apply simultaneously:

1. Per-batch: max_concurrency limits threads for THIS invocation.
2. System-wide: global and per-mcp_server semaphores (configured via config.yaml `execution.max_concurrency and per-mcp_server max_concurrency`) provide cross-batch backpressure.

All calls are submitted to the thread pool at once. Semaphores gate execution -- a call starts as soon as a slot frees up, without waiting for the entire batch wave to complete.

Args: calls: list[{mcp_server, tool, arguments, timeout?}] - Invocations to execute max_concurrency: int - Parallel workers for this batch (default: 10, range: 1-50) timeout: float - Batch timeout in seconds (default: 60, range: 1-300) fail_fast: bool - Stop batch on first error (default: false) max_attempts: int - Total attempts per call including retries (default: 1, range: 1-10)

Returns: Success: { batch_id: str, success: true, total: int, succeeded: int, failed: int, elapsed_ms: float, results: [{ index: int, call_id: str, success: true, result: any, error: null, error_type: null, elapsed_ms: float }] } Partial failure: { batch_id: str, success: false, total: int, succeeded: int, failed: int, elapsed_ms: float, results: [{ index: int, call_id: str, success: bool, result: any | null, error: str | null, error_type: str | null, elapsed_ms: float, retry_metadata?: {attempts: int, retries: list} }] } Validation error: { batch_id: str, success: false, error: "Validation failed", validation_errors: [{index: int, field: str, message: str}] } Truncated result: Individual result contains additional fields: {truncated: true, truncated_reason: str, original_size_bytes: int, continuation_id: str} Retrieve full data with hangar_fetch_continuation(continuation_id).

Example: # Single call - success hangar_call(calls=[{"mcp_server": "math", "tool": "add", "arguments": {"a": 1, "b": 2}}]) # {"batch_id": "abc-123", "success": true, "total": 1, "succeeded": 1, "failed": 0, # "elapsed_ms": 45.2, "results": [{"index": 0, "call_id": "def-456", # "success": true, "result": 3, "error": null, "elapsed_ms": 42.1}]}

# Validation error - unknown mcp_server hangar_call(calls=[{"mcp_server": "unknown", "tool": "x", "arguments": {}}]) # {"batch_id": "abc-123", "success": false, "error": "Validation failed", # "validation_errors": [{"index": 0, "field": "mcp_server", "message": "..."}]}

# Partial failure - some succeed, some fail hangar_call(calls=[ {"mcp_server": "math", "tool": "add", "arguments": {"a": 1, "b": 2}}, {"mcp_server": "math", "tool": "divide", "arguments": {"a": 1, "b": 0}} ]) # {"batch_id": "...", "success": false, "total": 2, "succeeded": 1, "failed": 1, # "results": [ # {"index": 0, "success": true, "result": 3, ...}, # {"index": 1, "success": false, "error": "division by zero", "error_type": "ValueError"} # ]}

# With retry - shows retry_metadata on failure hangar_call(calls=[...], max_attempts=3) # On failure: {"results": [{"retry_metadata": {"attempts": 3, "retries": [...]}, ...}]}

Delete a cached continuation to free resources.

CHOOSE THIS when: done with continuation data and want to free memory now. SKIP THIS for normal use - cached entries auto-expire based on TTL.

Side effects: Removes the cached response from memory.

Args: continuation_id: str - ID of cached continuation (starts with "cont_")

Returns: Success: {deleted: true, continuation_id: str} Not found: {deleted: false, continuation_id: str} Cache unavailable: {deleted: false, continuation_id: str, error: str}

Example: hangar_delete_continuation("cont_abc123_0_f8a2b3c4") # {"deleted": true, "continuation_id": "cont_abc123_0_f8a2b3c4"}

hangar_delete_continuation("cont_nonexistent") # {"deleted": false, "continuation_id": "cont_nonexistent"}

hangar_delete_continuation("cont_x") # when truncation disabled # {"deleted": false, "continuation_id": "cont_x", "error": "Truncation cache not available"}

Get configuration and runtime info for a mcp_server or group.

CHOOSE THIS when: you need mcp_server config, health history, or group membership. CHOOSE hangar_tools when: you need tool schemas for invoking. CHOOSE hangar_status when: you need quick overview of all mcp_servers.

Side effects: None (read-only).

Args: mcp_server: str - McpServer ID or Group ID

Returns: McpServer: { mcp_server: str, state: str, mode: str, alive: bool, tools: [{name, description, inputSchema}], health: {consecutive_failures: int, last_check: str, ...}, idle_time: float, meta: object } Group: { group_id: str, description: str, state: str, strategy: str, min_healthy: int, healthy_count: int, total_members: int, is_available: bool, circuit_open: bool, members: [{id, state, in_rotation, weight, priority, consecutive_failures}] } Error: ValueError with "unknown_mcp_server: <id>"

Example: hangar_details("math") # {"mcp_server": "math", "state": "ready", "mode": "subprocess", # "alive": true, "tools": [...], "health": {"consecutive_failures": 0}, # "idle_time": 12.5, "meta": {}}

hangar_details("llm-group") # {"group_id": "llm-group", "state": "ready", "strategy": "round_robin", # "healthy_count": 2, "total_members": 3, "members": [...]}

hangar_details("unknown") # Error: unknown_mcp_server: unknown

Trigger immediate discovery scan across all enabled sources.

CHOOSE THIS when: you deployed new mcp_servers and want to find them now. CHOOSE hangar_discovered when: listing mcp_servers already found, awaiting approval. CHOOSE hangar_sources when: checking which discovery sources are working.

Side effects: Scans all enabled sources. Updates pending mcp_server list.

Args: None

Returns: Success: { discovered_count: int, registered_count: int, updated_count: int, deregistered_count: int, quarantined_count: int, error_count: int, duration_ms: float, source_results: {<source_type>: int} } Not configured: {error: str}

Example: hangar_discover() # {"discovered_count": 2, "registered_count": 1, "updated_count": 0, # "deregistered_count": 0, "quarantined_count": 0, "error_count": 0, # "duration_ms": 142.5, "source_results": {"kubernetes": 2}}

hangar_discover() # when not configured # {"error": "Discovery not configured. Enable discovery in config.yaml"}

List mcp_servers pending registration (awaiting approval).

CHOOSE THIS when: reviewing what mcp_servers were found before approving. CHOOSE hangar_discover when: triggering a new scan to find mcp_servers. CHOOSE hangar_approve when: ready to register a pending mcp_server.

Side effects: None (read-only).

Args: None

Returns: Success: { pending: [{ name: str, source: str, mode: str, discovered_at: str, fingerprint: str }] } Not configured: {error: str}

Example: hangar_discovered() # {"pending": [{"name": "new-mcp_server", "source": "kubernetes", # "mode": "remote", "discovered_at": "2024-01-15T10:30:00Z", "fingerprint": "abc123"}]}

hangar_discovered() # when no pending mcp_servers # {"pending": []}

hangar_discovered() # when not configured # {"error": "Discovery not configured. Enable discovery in config.yaml"}

Fetch full or remaining content from a truncated batch response.

CHOOSE THIS when: hangar_call returned truncated result with continuation_id. CHOOSE hangar_delete_continuation when: done with data and want to free memory. SKIP THIS when: result was not truncated (no continuation_id in response).

Side effects: None (read-only cache access).

Args: continuation_id: str - ID from truncated response (starts with "cont_") offset: int - Byte offset to start reading (default: 0) limit: int - Max bytes to retrieve (default: 500000, max: 2000000)

Returns: Success: { found: true, data: any, total_size_bytes: int, offset: int, has_more: bool, complete: bool } Not found: {found: false, error: str} Cache unavailable: {found: false, error: str}

Example: hangar_fetch_continuation("cont_abc123_0_f8a2b3c4") # {"found": true, "data": {"result": "full data here"}, "total_size_bytes": 1024, # "offset": 0, "has_more": false, "complete": true}

hangar_fetch_continuation("cont_abc123_0_f8a2b3c4", offset=500000, limit=500000) # {"found": true, "data": ..., "has_more": true, "complete": false, ...}

hangar_fetch_continuation("cont_expired") # {"found": false, "error": "Continuation not found (may have expired)"}

hangar_fetch_continuation("cont_x") # when truncation disabled # {"found": false, "error": "Truncation cache not available (truncation may be disabled)"}

List all mcp_server groups with per-member details.

CHOOSE THIS when: you need member-level details (rotation, weights, individual states). CHOOSE hangar_list when: you need group summaries with mcp_server list. CHOOSE hangar_details when: you need full info for a specific group.

Side effects: None (read-only).

Args: None

Returns: { groups: [{ group_id: str, description: str, state: str, strategy: str, min_healthy: int, healthy_count: int, total_members: int, is_available: bool, circuit_open: bool, members: [{id, state, in_rotation, weight, priority, consecutive_failures}] }] }

Example: hangar_group_list() # {"groups": [{"group_id": "llm-group", "state": "ready", "strategy": "round_robin", # "healthy_count": 2, "total_members": 3, "members": [ # {"id": "llm-1", "state": "ready", "in_rotation": true, "weight": 1}, # {"id": "llm-2", "state": "ready", "in_rotation": true, "weight": 1}, # {"id": "llm-3", "state": "degraded", "in_rotation": false, "weight": 1} # ]}]}

hangar_group_list() # when no groups configured # {"groups": []}

Force rebalancing for a mcp_server group.

CHOOSE THIS when: after manual intervention, or to recover members faster than auto. CHOOSE hangar_start when: starting all group members from cold state. SKIP THIS for normal operation - rebalancing happens automatically on health failures.

Side effects: Re-checks all members. Recovered members rejoin rotation, failed removed.

Args: group: str - Group ID

Returns: { group_id: str, state: str, healthy_count: int, total_members: int, members_in_rotation: list[str] } Error: ValueError with "unknown_group: <id>"

Example: hangar_group_rebalance("llm-group") # {"group_id": "llm-group", "state": "ready", "healthy_count": 2, # "total_members": 3, "members_in_rotation": ["llm-1", "llm-2"]}

hangar_group_rebalance("unknown") # Error: unknown_group: unknown

Get registry health status including security metrics.

CHOOSE THIS when: quick health check, monitoring dashboard, security overview. CHOOSE hangar_metrics when: detailed per-mcp_server stats, tool call counts, Prometheus. CHOOSE hangar_status when: human-readable dashboard with visual indicators.

Side effects: None (read-only).

Args: None

Returns: { status: str, mcp_servers: {total: int, by_state: {cold: int, ready: int, degraded: int, dead: int}}, groups: {total: int, by_state: object, total_members: int, healthy_members: int}, security: {rate_limiting: {active_buckets: int, config: object}} }

Example: hangar_health() # {"status": "healthy", # "mcp_servers": {"total": 3, "by_state": {"ready": 2, "cold": 1}}, # "groups": {"total": 1, "by_state": {"ready": 1}, "total_members": 3, "healthy_members": 2}, # "security": {"rate_limiting": {"active_buckets": 5, "config": {...}}}}

List all mcp_servers and groups with precise numeric values.

CHOOSE THIS when: you need exact data for processing, filtering, or automation. CHOOSE hangar_status when: you need human-readable dashboard with visual indicators. CHOOSE hangar_group_list when: you need member-level details (rotation, weights).

Side effects: None (read-only).

Args: state_filter: str - Filter by state: "cold", "ready", "degraded", "dead" (default: null)

Returns: { mcp_servers: [{ mcp_server: str, state: str, mode: str, alive: bool, tools_count: int, health_status: str, tools_predefined: bool, description?: str }], groups: [{group_id, state, strategy, healthy_count, total_members, ...}], runtime_mcp_servers: [{ mcp_server: str, state: str, source: str, verified: bool, ephemeral: bool, loaded_at: str, lifetime_seconds: float }] }

Example: hangar_list() # {"mcp_servers": [{"mcp_server": "math", "state": "ready", "mode": "subprocess", # "alive": true, "tools_count": 2, "health_status": "healthy"}], # "groups": [], "runtime_mcp_servers": []}

hangar_list(state_filter="ready") # Returns only mcp_servers/groups in "ready" state

hangar_list(state_filter="cold") # {"mcp_servers": [{"mcp_server": "sqlite", "state": "cold", "alive": false}], ...}

Load an MCP mcp_server from the official registry at runtime.

CHOOSE THIS when: you need a capability not in configured mcp_servers. CHOOSE hangar_start when: mcp_server is already configured, just needs starting. CHOOSE hangar_call when: mcp_server is configured and you want to invoke it directly. NOTE: Loaded mcp_servers are ephemeral (lost on restart).

Side effects: Downloads and starts mcp_server process. Adds to runtime registry.

Get detailed metrics for mcp_servers, groups, and system components.

CHOOSE THIS when: debugging, performance analysis, Prometheus scraping, tool call stats. CHOOSE hangar_health when: quick health check with security metrics. CHOOSE hangar_status when: human-readable overview for display.

Side effects: None (read-only).

Args: format: str - Output format: "json" or "prometheus" (default: "json")

Returns: JSON format: { mcp_servers: {<id>: {state, mode, tools_count, invocations, errors, avg_latency_ms}}, groups: {<id>: {state, strategy, total_members, healthy_members}}, tool_calls: {<mcp_server.tool>: {count, errors}}, discovery: object, errors: {<type>: int}, performance: object, summary: {total_mcp_servers, total_groups, total_tool_calls, total_errors} } Prometheus format: {metrics: str}

Example: hangar_metrics() # {"mcp_servers": {"math": {"state": "ready", "mode": "subprocess", "invocations": 42}}, # "tool_calls": {"math.add": {"count": 30, "errors": 0}}, # "summary": {"total_mcp_servers": 1, "total_tool_calls": 42, "total_errors": 0}}

hangar_metrics(format="prometheus") # {"metrics": "# HELP mcp_hangar_tool_calls_total ...\nmcp_hangar_tool_calls_total{...} 42"}

List quarantined mcp_servers with failure reasons.

CHOOSE THIS when: investigating why mcp_servers failed validation or health checks. CHOOSE hangar_discovered when: listing mcp_servers that passed validation. CHOOSE hangar_approve when: ready to restore a quarantined mcp_server.

Side effects: None (read-only).

Args: None

Returns: Success: { quarantined: [{ name: str, source: str, reason: str, quarantine_time: str }] } Not configured: {error: str}

Example: hangar_quarantine() # {"quarantined": [{"name": "broken-mcp_server", "source": "docker", # "reason": "health_check_failed", "quarantine_time": "2024-01-15T10:30:00Z"}]}

hangar_quarantine() # when no quarantined mcp_servers # {"quarantined": []}

hangar_quarantine() # when not configured # {"error": "Discovery not configured. Enable discovery in config.yaml"}

Reload configuration from file and apply changes.

CHOOSE THIS when: you modified config.yaml and want to apply changes without restarting. NOTE: Preserves unchanged mcp_servers (no restart), only affects added/removed/updated.

Side effects: Stops/starts mcp_servers based on configuration changes.

Args: graceful: bool - If True, wait for idle state before stopping (default: true)

Returns: { status: "success"|"failed", message: str, mcp_servers_added: [str], mcp_servers_removed: [str], mcp_servers_updated: [str], mcp_servers_unchanged: [str], duration_ms: float }

Example: hangar_reload_config() # {"status": "success", "message": "Configuration reloaded successfully", # "mcp_servers_added": ["new-mcp_server"], "mcp_servers_removed": [], # "mcp_servers_updated": ["modified-mcp_server"], "mcp_servers_unchanged": ["stable-mcp_server"], # "duration_ms": 123.45}

hangar_reload_config(graceful=false) # Immediate reload without waiting for idle state

List discovery sources with health status.

CHOOSE THIS when: diagnosing why mcp_servers are not being discovered. CHOOSE hangar_discover when: triggering a scan after fixing source issues. CHOOSE hangar_health when: checking overall system health, not just discovery.

Side effects: None (read-only).

Args: None

Returns: Success: { sources: [{ id: str, source_type: str, mode: str, is_healthy: bool, is_enabled: bool, last_discovery: str | null, mcp_servers_count: int, error_message: str | null }] } Not configured: {error: str}

id is the addressable id of the source, the same one the REST API uses in /api/discovery/sources/{id}. A source declared in config.yaml derives its id from its source_type, so the id is the same after a restart. Every source in this listing carries an id; the REST listing omits the id of a source the discovery registry no longer knows, because there its sub-routes would 404 on it.

Example: hangar_sources() # {"sources": [ # {"id": "7afbd3ca-c2b2-5516-a3d8-408e7c75580e", # "source_type": "kubernetes", "mode": "additive", "is_healthy": true, # "is_enabled": true, "last_discovery": "2024-01-15T10:30:00Z", # "mcp_servers_count": 5, "error_message": null}, # {"id": "28018ad1-4d9d-54dc-9e4e-c5d856af4612", # "source_type": "docker", "mode": "additive", "is_healthy": false, # "is_enabled": true, "last_discovery": null, # "mcp_servers_count": 0, "error_message": "socket not found"} # ]}

hangar_sources() # when not configured # {"error": "Discovery not configured. Enable discovery in config.yaml"}

Start a mcp_server or all members of a group.

CHOOSE THIS when: you need to verify startup works or pre-warm a specific mcp_server/group. CHOOSE hangar_warm when: you need to pre-warm multiple mcp_servers at once. CHOOSE hangar_call when: you want to invoke a tool (auto-starts cold mcp_servers). SKIP THIS when: you just want to call a tool - hangar_call auto-starts mcp_servers.

Side effects: Starts mcp_server process/container. State changes from cold to ready.

Args: mcp_server: str - McpServer ID or Group ID

Returns: McpServer: {mcp_server: str, state: str, tools: list[str]} Group: {group: str, state: str, members_started: int, healthy_count: int, total_members: int} Error: ValueError with "unknown_mcp_server: <id>" or "unknown_group: <id>"

Example: hangar_start("math") # {"mcp_server": "math", "state": "ready", "tools": ["add", "multiply"]}

hangar_start("llm-group") # {"group": "llm-group", "state": "ready", "members_started": 2, # "healthy_count": 2, "total_members": 3}

hangar_start("unknown") # Error: unknown_mcp_server: unknown

Get human-readable status dashboard of the registry.

CHOOSE THIS when: you need to display status to user or quick health overview. CHOOSE hangar_list when: you need exact values for processing or filtering. CHOOSE hangar_health when: you need system health with security metrics.

Side effects: None (read-only).

Args: None

Returns: { mcp_servers: [{id: str, indicator: str, state: str, mode: str, last_used?: str}], groups: [{id: str, indicator: str, state: str, healthy_members: int, total_members: int}], runtime_mcp_servers: [{id: str, indicator: str, state: str, source: str, verified: bool}], summary: {healthy_mcp_servers: int, total_mcp_servers: int, uptime: str, uptime_seconds: float}, formatted: str } Indicator values: [READY], [COLD], [STARTING], [DEGRADED], [DEAD]

Example: hangar_status() # {"mcp_servers": [{"id": "math", "indicator": "[READY]", "state": "ready", "mode": "subprocess"}], # "groups": [], "runtime_mcp_servers": [], # "summary": {"healthy_mcp_servers": 1, "total_mcp_servers": 1, "uptime": "2h 15m"}, # "formatted": "...ASCII dashboard..."}

Stop a mcp_server or all members of a group.

CHOOSE THIS when: you need to force restart or free resources immediately. CHOOSE hangar_unload when: removing a hot-loaded mcp_server permanently. SKIP THIS when: "cleaning up" between calls - mcp_servers auto-manage via idle_ttl.

Side effects: Stops mcp_server process/container. State changes to cold.

Args: mcp_server: str - McpServer ID or Group ID

Returns: McpServer: {stopped: str, reason: str} Group: {group: str, state: str, stopped: bool} Error: ValueError with "unknown_mcp_server: <id>"

Example: hangar_stop("math") # {"stopped": "math", "reason": "manual"}

hangar_stop("llm-group") # {"group": "llm-group", "state": "cold", "stopped": true}

hangar_stop("unknown") # Error: unknown_mcp_server: unknown

Get tool schemas (JSON Schema) for a mcp_server.

CHOOSE THIS when: you need tool names and input schemas before calling. CHOOSE hangar_details when: you need mcp_server config, health, or runtime info. CHOOSE hangar_call when: you already know the tool name and want to invoke it.

Side effects: May start a cold mcp_server to discover tools.

Args: mcp_server: str - McpServer ID or Group ID

Returns: McpServer: { mcp_server: str, state: str, predefined: bool, tools: [{name: str, description: str, inputSchema: object}] } Group: { mcp_server: str, group: true, tools: [{name: str, description: str, inputSchema: object}] } Error: ValueError with "unknown_mcp_server: <id>" or "no_healthy_members_in_group: <id>"

Example: hangar_tools("math") # {"mcp_server": "math", "state": "ready", "predefined": false, # "tools": [{"name": "add", "description": "Add two numbers", # "inputSchema": {"properties": {"a": {"type": "number"}, "b": {"type": "number"}}}}]}

hangar_tools("llm-group") # {"mcp_server": "llm-group", "group": true, "tools": [...]}

hangar_tools("unknown") # Error: unknown_mcp_server: unknown

Unload a hot-loaded mcp_server.

CHOOSE THIS when: removing a mcp_server loaded via hangar_load. CHOOSE hangar_stop when: stopping a configured mcp_server (will auto-restart on call). NOTE: Only works for hot-loaded mcp_servers, not configured ones.

Side effects: Stops mcp_server process. Removes from runtime registry.

Args: mcp_server: str - McpServer ID (from hangar_load result)

Returns: Success: {status: "unloaded", mcp_server: str, message: str, lifetime_seconds: float} Not hot-loaded: {status: "not_hot_loaded", mcp_server: str, message: str} Not configured: {status: "failed", message: str}

Example: hangar_unload("mcp-server-time") # {"status": "unloaded", "mcp_server": "mcp-server-time", # "message": "Successfully unloaded 'mcp-server-time'", "lifetime_seconds": 3600}

hangar_unload("math") # {"status": "not_hot_loaded", "mcp_server": "math", # "message": "McpServer 'math' was not hot-loaded. Use hangar_stop for configured mcp_servers."}

Pre-start mcp_servers to avoid cold start latency on first hangar_call.

CHOOSE THIS when: warming multiple mcp_servers before latency-sensitive batch. CHOOSE hangar_start when: starting a specific mcp_server or group. CHOOSE hangar_call when: invoking tools (auto-starts, latency acceptable). SKIP THIS for normal use - hangar_call auto-starts mcp_servers.

Side effects: Starts specified mcp_server processes. Groups are skipped.

Args: mcp_servers: str - Comma-separated mcp_server IDs, or null to warm all

Returns: { warmed: list[str], already_warm: list[str], failed: list[{id: str, error: str}], summary: str }

Example: hangar_warm("math,sqlite") # {"warmed": ["math"], "already_warm": ["sqlite"], "failed": [], # "summary": "Warmed 1 mcp_servers, 1 already warm, 0 failed"}

hangar_warm("unknown,math") # {"warmed": ["math"], "already_warm": [], # "failed": [{"id": "unknown", "error": "McpServer not found"}], # "summary": "Warmed 1 mcp_servers, 0 already warm, 1 failed"}

hangar_warm() # {"warmed": ["math", "sqlite"], "already_warm": [], "failed": [], # "summary": "Warmed 2 mcp_servers, 0 already warm, 0 failed"}