MCP Tools Reference¶

Complete reference for all MCP protocol tools exposed by MCP Hangar. These tools are callable by any MCP client (Claude Desktop, LM Studio, custom integrations).

Quick Reference¶

Lifecycle¶

hangar_list {#hangar_list}¶

List all configured MCP servers, groups, and runtime (hot-loaded) MCP servers with current state, mode, and tool counts.

Parameters:

Side Effects: None (read-only).

Returns:

Example:

// Request
{"state_filter": "ready"}

// Response
{
  "mcp_servers": [
    {"mcp_server": "math", "state": "ready", "mode": "subprocess", "alive": true,
     "tools_count": 4, "health_status": "healthy", "tools_predefined": false}
  ],
  "groups": [],
  "runtime_mcp_servers": []
}

hangar_start {#hangar_start}¶

Start a MCP server or group. Transitions the MCP server from COLD to READY.

Parameters:

Side Effects: Starts MCP server process or container. State transitions from COLD to READY.

Returns:

For a MCP server:

For a group:

Example:

// Request
{"mcp_server": "math"}

// Response
{"mcp_server": "math", "state": "ready", "tools": ["add", "subtract", "multiply", "divide"]}

Errors: ValueError("unknown_mcp_server: <id>"), ValueError("unknown_group: <id>")

hangar_stop {#hangar_stop}¶

Stop a running MCP server or group.

Parameters:

Side Effects: Stops MCP server process or container. State transitions to COLD.

Returns:

For a MCP server:

For a group:

Example:

// Request
{"mcp_server": "math"}

// Response
{"stopped": "math", "reason": "manual_stop"}

Errors: ValueError("unknown_mcp_server: <id>")

hangar_status {#hangar_status}¶

Human-readable health dashboard with state indicators for all MCP servers and groups.

Parameters: None.

Side Effects: None (read-only).

Returns:

Indicator values: [READY], [COLD], [STARTING], [DEGRADED], [DEAD].

Example:

// Request
{}

// Response
{
  "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": "[READY] math (subprocess, 4 tools)"
}

hangar_reload_config {#hangar_reload_config}¶

Reload configuration from disk, applying MCP server additions, removals, and updates.

Parameters:

Side Effects: Stops removed/modified MCP servers, registers new MCP servers, updates changed MCP servers.

Returns:

On failure, the response includes error_type instead of MCP server lists.

Example:

// Request
{"graceful": true}

// Response
{
  "status": "success", "message": "Configuration reloaded",
  "mcp_servers_added": ["new-api"], "mcp_servers_removed": [],
  "mcp_servers_updated": ["math"], "mcp_servers_unchanged": ["filesystem"],
  "duration_ms": 45.2
}

Hot-Loading¶

hangar_load (async) {#hangar_load}¶

Load a MCP server from the MCP registry at runtime. Hot-loaded MCP servers are ephemeral and lost on server restart.

Parameters:

Side Effects: Downloads and starts the MCP server process. Adds to the runtime registry.

Returns:

The primary success response:

Other possible status values: "ambiguous" (multiple matches found, includes matches list), "not_found" (no match in registry), "missing_secrets" (required secrets not configured, includes missing list and instructions), "unverified" (MCP server not verified, use force_unverified to override), "failed" (configuration error).

Example:

// Request
{"name": "filesystem", "allow_tools": ["read_*"]}

// Response
{"status": "loaded", "mcp_server": "filesystem", "tools": ["read_file", "read_directory"]}

hangar_unload {#hangar_unload}¶

Unload a hot-loaded MCP server. Only works for MCP servers loaded via hangar_load.

Parameters:

Side Effects: Stops the MCP server process and removes it from the runtime registry.

Returns:

Example:

// Request
{"mcp_server": "filesystem"}

// Response
{"status": "unloaded", "mcp_server": "filesystem", "message": "MCP Server unloaded",
 "lifetime_seconds": 3600.5}

MCP Server¶

hangar_tools {#hangar_tools}¶

List the tools available on a MCP server or group. Tool access filtering (allow_list/deny_list) is applied.

Parameters:

Side Effects: May start a cold MCP server to discover its tools.

Returns:

For groups, the response includes group: true instead of predefined.

Example:

// Request
{"mcp_server": "math"}

// Response
{
  "mcp_server": "math", "state": "ready", "predefined": false,
  "tools": [
    {"name": "add", "description": "Add two numbers",
     "inputSchema": {"type": "object", "properties": {"a": {"type": "number"}, "b": {"type": "number"}}}}
  ]
}

Errors: ValueError("unknown_mcp_server: <id>"), ValueError("no_healthy_members_in_group: <id>")

hangar_details {#hangar_details}¶

Detailed information about a MCP server or group, including health tracking, idle time, and tool access policy.

Parameters:

Side Effects: None (read-only).

Returns:

For a MCP server:

For a group:

Example:

// Request
{"mcp_server": "math"}

// Response
{
  "mcp_server": "math", "state": "ready", "mode": "subprocess", "alive": true,
  "tools": [{"name": "add", "description": "Add two numbers"}],
  "health": {"consecutive_failures": 0, "last_check": "2026-01-15T10:30:00Z"},
  "idle_time": 45.2,
  "tools_policy": {"type": "open", "has_allow_list": false, "has_deny_list": false}
}

Errors: ValueError("unknown_mcp_server: <id>")

hangar_warm {#hangar_warm}¶

Pre-start one or more MCP servers so the first tool call does not incur cold-start latency. Groups are skipped.

Parameters:

Side Effects: Starts specified MCP server processes.

Returns:

Example:

// Request
{"mcp_servers": "math,filesystem"}

// Response
{
  "warmed": ["math"], "already_warm": ["filesystem"], "failed": [],
  "summary": "1 warmed, 1 already warm, 0 failed"
}

Health¶

hangar_health {#hangar_health}¶

System-wide health summary with MCP server state counts and security information.

Parameters: None.

Side Effects: None (read-only).

Returns:

Example:

// Request
{}

// Response
{
  "status": "healthy",
  "mcp_servers": {"total": 3, "by_state": {"ready": 2, "cold": 1}},
  "groups": {"total": 1, "by_state": {"healthy": 1}, "total_members": 3, "healthy_members": 3},
  "security": {"rate_limiting": {"active_buckets": 0, "config": {"rps": 10, "burst": 20}}}
}

hangar_metrics {#hangar_metrics}¶

MCP Server metrics in JSON or Prometheus exposition format.

Parameters:

Side Effects: None (read-only).

Returns (JSON format):

When format is "prometheus", the response contains a single metrics field with Prometheus exposition text.

Example:

// Request
{"format": "json"}

// Response
{
  "mcp_servers": {"math": {"state": "ready", "mode": "subprocess", "tools_count": 4,
                          "invocations": 150, "errors": 2, "avg_latency_ms": 12.3}},
  "groups": {},
  "tool_calls": {"math.add": {"count": 100, "errors": 0}},
  "summary": {"total_mcp_servers": 1, "total_groups": 0, "total_tool_calls": 150, "total_errors": 2}
}

Discovery¶

hangar_discover (async) {#hangar_discover}¶

Trigger a discovery scan across all enabled sources. Discovered MCP servers are added to the pending list for approval (unless auto_register is enabled).

Parameters: None.

Side Effects: Scans all enabled discovery sources. Updates the pending MCP server list.

Returns:

Returns {error: "Discovery not configured. Enable discovery in config.yaml"} when discovery is not enabled.

Example:

// Request
{}

// Response
{
  "discovered_count": 5, "registered_count": 3, "updated_count": 1,
  "deregistered_count": 0, "quarantined_count": 1, "error_count": 0,
  "duration_ms": 1250.0, "source_results": {"docker": 3, "filesystem": 2}
}

hangar_discovered {#hangar_discovered}¶

List MCP servers discovered but not yet registered (pending approval).

Parameters: None.

Side Effects: None (read-only).

Returns:

Returns {error: ...} when discovery is not configured.

Example:

// Request
{}

// Response
{
  "pending": [
    {"name": "new-api", "source": "docker", "mode": "remote",
     "discovered_at": "2026-01-15T10:30:00Z", "fingerprint": "abc123"}
  ]
}

hangar_quarantine {#hangar_quarantine}¶

List MCP servers that failed health checks during discovery and were quarantined.

Parameters: None.

Side Effects: None (read-only).

Returns:

Returns {error: ...} when discovery is not configured.

Example:

// Request
{}

// Response
{
  "quarantined": [
    {"name": "broken-api", "source": "docker", "reason": "health_check_failed",
     "quarantine_time": "2026-01-15T10:30:00Z"}
  ]
}

hangar_approve (async) {#hangar_approve}¶

Approve a pending or quarantined MCP server for registration.

Parameters:

Side Effects: Registers the MCP server in COLD state. Removes from pending or quarantine list.

Returns:

Returns {error: ...} when discovery is not configured.

Example:

// Request
{"mcp_server": "new-api"}

// Response
{"approved": true, "mcp_server": "new-api", "status": "registered"}

hangar_sources (async) {#hangar_sources}¶

List the status of all configured discovery sources.

Parameters: None.

Side Effects: None (read-only).

Returns:

Returns {error: ...} when discovery is not configured.

Example:

// Request
{}

// Response
{
  "sources": [
    {"source_type": "docker", "mode": "additive", "is_healthy": true,
     "is_enabled": true, "last_discovery": "2026-01-15T10:30:00Z",
     "mcp_servers_count": 3, "error_message": null}
  ]
}

Groups¶

hangar_group_list {#hangar_group_list}¶

List all MCP server groups with member details, health state, and load balancing configuration.

Parameters: None.

Side Effects: None (read-only).

Returns:

Each member in the members list contains: id, state, in_rotation, weight, priority, consecutive_failures.

Example:

// Request
{}

// Response
{
  "groups": [
    {
      "group_id": "llm-group", "description": "LLM pool", "state": "healthy",
      "strategy": "round_robin", "min_healthy": 1, "healthy_count": 2,
      "total_members": 2, "is_available": true, "circuit_open": false,
      "members": [
        {"id": "llm-1", "state": "ready", "in_rotation": true, "weight": 50,
         "priority": 1, "consecutive_failures": 0},
        {"id": "llm-2", "state": "ready", "in_rotation": true, "weight": 50,
         "priority": 2, "consecutive_failures": 0}
      ]
    }
  ]
}

hangar_group_rebalance {#hangar_group_rebalance}¶

Rebalance a group by re-checking all members. Recovered members rejoin rotation, failed members are removed. Resets the circuit breaker.

Parameters:

Side Effects: Re-checks all members. Updates rotation membership. Resets circuit breaker.

Returns:

Example:

// Request
{"group": "llm-group"}

// Response
{
  "group_id": "llm-group", "state": "healthy", "healthy_count": 2,
  "total_members": 2, "members_in_rotation": ["llm-1", "llm-2"]
}

Errors: ValueError("unknown_group: <id>")

Batch and Continuation¶

hangar_call {#hangar_call}¶

Invoke tools on MCP servers. Supports single calls and parallel batch execution with two-level concurrency control (per-batch and system-wide).

Parameters:

Side Effects: May start cold MCP servers. Executes tool calls on MCP servers.

Returns:

On validation failure, the response contains validation_errors (list of {index, field, message}) instead of results. Individual results may include truncated: true with a continuation_id for large responses -- use hangar_fetch_continuation to retrieve the full data.

Results with retries include retry_metadata with attempts and retries counts.

Example:

// Request
{
  "calls": [
    {"mcp_server": "math", "tool": "add", "arguments": {"a": 1, "b": 2}},
    {"mcp_server": "math", "tool": "multiply", "arguments": {"a": 3, "b": 4}}
  ],
  "max_concurrency": 5
}

// Response
{
  "batch_id": "batch-abc123", "success": true, "total": 2,
  "succeeded": 2, "failed": 0, "elapsed_ms": 45.2,
  "results": [
    {"index": 0, "call_id": "call-1", "success": true, "result": 3,
     "error": null, "error_type": null, "elapsed_ms": 20.1},
    {"index": 1, "call_id": "call-2", "success": true, "result": 12,
     "error": null, "error_type": null, "elapsed_ms": 22.8}
  ]
}

hangar_fetch_continuation {#hangar_fetch_continuation}¶

Fetch full data for a truncated batch response. Continuation IDs are returned when individual call results exceed the response size limit.

Parameters:

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

Returns:

Returns {found: false, error: "Continuation not found (may have expired)"} when the continuation ID is invalid or expired.

Example:

// Request
{"continuation_id": "cont_abc123", "offset": 0, "limit": 500000}

// Response
{
  "found": true, "data": "...full response content...",
  "total_size_bytes": 250000, "offset": 0, "has_more": false, "complete": true
}

Errors: ValueError if continuation_id is empty, does not start with "cont_", or offset is negative.

hangar_delete_continuation {#hangar_delete_continuation}¶

Delete cached continuation data to free memory.

Parameters:

Side Effects: Removes the cached response from memory.

Returns:

Returns {deleted: false, continuation_id: "..."} when the ID is not found. Returns {deleted: false, continuation_id: "...", error: "..."} when the truncation cache is unavailable.

Example:

// Request
{"continuation_id": "cont_abc123"}

// Response
{"deleted": true, "continuation_id": "cont_abc123"}

Errors: ValueError if continuation_id is empty.