MCP Ambari API Service Lifecycle Operations: Start, Stop, and Restart Guide

The MCP Ambari API provides six distinct service lifecycle operations—start_service, stop_service, restart_service, start_all_services, stop_all_services, and restart_all_services—all implemented in src/mcp_ambari_api/mcp_main.py and exposed via FastMCP tool decorators.

The call518/mcp-ambari-api repository implements a Model Context Protocol (MCP) server that wraps Apache Ambari's REST API, enabling programmatic control over Hadoop cluster services. Understanding these service lifecycle operations is essential for automating cluster maintenance, rolling upgrades, and operational workflows through LLM clients or other MCP-compatible tools.

Available Service Lifecycle Operations

All lifecycle tools are registered in src/mcp_ambari_api/mcp_main.py using the @mcp.tool() decorator and follow a consistent validation and execution pattern.

Single Service Operations

Target individual services by name (e.g., HDFS, YARN, HBASE):

• start_service(service_name: str) – Transitions a service from INSTALLED to STARTED state. Defined at lines 935–960.

• stop_service(service_name: str) – Transitions a service from STARTED to INSTALLED state. Defined at lines 1025–1052.

• restart_service(service_name: str) – Executes sequential stop and start operations, generating two separate request IDs. Defined at lines 1189–1240.

Bulk Cluster Operations

Execute operations across all services simultaneously:

• start_all_services() – Initiates parallel start requests for the entire cluster. Defined at lines 754–795.

• stop_all_services() – Gracefully stops all cluster services. Defined at lines 838–878.

• restart_all_services() – Performs coordinated bulk restart with dependency-aware sequencing. Defined at lines 1686–1735.

Implementation Architecture

Each service lifecycle operation follows a four-phase execution pattern implemented in mcp_main.py:

1. Validation – Verifies service or cluster existence via make_ambari_request before attempting state changes.

2. State Inspection – Checks current service state (STARTED, INSTALLED, etc.) to prevent redundant operations and ensure valid transitions.

3. Request Issuance – Submits a PUT request to the Ambari REST endpoint with a JSON payload setting ServiceInfo.state to "STARTED" or "INSTALLED" as appropriate. Bulk operations target /clusters/{cluster_name}/services with optional fallback endpoints.

4. Response Formatting – Returns structured output containing the request ID, status (ACCEPTED/COMPLETED), monitoring URL, and instructions to poll get_request_status(request_id) for asynchronous progress tracking.

Usage Examples

The following Python snippets demonstrate how MCP clients invoke these tools:

Start a Single Service

result = await client.call_tool("start_service", service_name="HDFS")
print(result)

Typical output:

START SERVICE: HDFS

Cluster: my_cluster
Service: HDFS
Previous State: INSTALLED
Request ID: 12345
Status: ACCEPTED
Monitor URL: http://ambari-host:8080/api/v1/clusters/my_cluster/requests/12345
Use get_request_status(request_id) to track progress.

Restart a Single Service

result = await client.call_tool("restart_service", service_name="HBASE")
print(result)

Output showing sequential operations:

RESTART SERVICE: HBASE
Stop Request ID: 12347
Start Request ID: 12348

Cluster: my_cluster
Service: HBASE
Initial State: STARTED
Stop Status: COMPLETED
Start Status: ACCEPTED
Start Monitor URL: http://ambari-host:8080/api/v1/clusters/my_cluster/requests/12348
Next: get_request_status(12348) for updates.

Bulk Stop All Services

result = await client.call_tool("stop_all_services")
print(result)

Output format:

STOP ALL SERVICES INITIATED

Cluster: my_cluster
Request ID: 12401
Status: ACCEPTED
Monitor URL: http://ambari-host:8080/api/v1/clusters/my_cluster/requests/12401
Note: This operation may take several minutes to complete.
Use get_request_status(12401) to track progress.

Key Source Files

File	Purpose	Location
src/mcp_ambari_api/mcp_main.py	Contains all six service lifecycle tool definitions (start_service, stop_service, restart_service, and bulk variants) with FastMCP registration.	View source
src/mcp_ambari_api/functions.py	Implements low-level HTTP client make_ambari_request, request status checking, and check_service_active_requests for concurrency safety.	View source
src/mcp_ambari_api/__init__.py	Registers the FastMCP instance and enables tool discovery for MCP clients.	View source

Summary

• Six operations cover all service lifecycle needs: three single-service (start_service, stop_service, restart_service) and three bulk cluster operations (start_all_services, stop_all_services, restart_all_services).
• Consistent API design across all tools with automatic request ID generation and status tracking URLs.
• Defensive programming includes pre-flight state validation and active request checking to prevent conflicting operations.
• Full async support via FastMCP framework, enabling non-blocking cluster orchestration from LLM agents or automation scripts.

Frequently Asked Questions

How does the restart operation handle failures between stop and start phases?

The restart_service function in mcp_main.py (lines 1189–1240) executes stop and start as discrete, sequential operations. If the stop phase fails or times out, the function returns immediately with the failure details and does not proceed to the start phase, ensuring services remain in a known state rather than partially restarted.

Can I track the progress of bulk operations after initiating them?

Yes. All service lifecycle operations return a request ID and a monitoring URL. According to the implementation in mcp_main.py, you should call get_request_status(request_id) with the returned ID to poll for completion status, percentage progress, and detailed task-level outputs from Ambari's backend.

What authentication does the MCP server use when calling Ambari endpoints?

The make_ambari_request helper in src/mcp_ambari_api/functions.py handles HTTP Basic Authentication using credentials configured via environment variables (AMBARI_USERNAME and AMBARI_PASSWORD). All lifecycle operations inherit this authentication automatically when communicating with the Ambari REST API.

Is there a way to restart only specific services rather than all services?

Yes. Use the restart_service tool for individual services by specifying the exact service name (case-sensitive). The bulk restart_all_services operation should only be used when you intend to restart the entire cluster, as it submits requests for every registered service simultaneously without filtering.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}