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

> Master MCP Ambari API service lifecycle operations. Learn to start stop and restart individual or all services using this comprehensive guide.

- Repository: [JungJungIn/mcp-ambari-api](https://github.com/call518/mcp-ambari-api)
- Tags: how-to-guide
- Published: 2026-02-26

---

**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`](https://github.com/call518/mcp-ambari-api/blob/main/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`](https://github.com/call518/mcp-ambari-api/blob/main/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](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/mcp_main.py#L935).

- **`stop_service(service_name: str)`** – Transitions a service from `STARTED` to `INSTALLED` state. Defined at [lines 1025–1052](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/mcp_main.py#L1025).

- **`restart_service(service_name: str)`** – Executes sequential stop and start operations, generating two separate request IDs. Defined at [lines 1189–1240](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/mcp_main.py#L1189).

### 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](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/mcp_main.py#L754).

- **`stop_all_services()`** – Gracefully stops all cluster services. Defined at [lines 838–878](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/mcp_main.py#L838).

- **`restart_all_services()`** – Performs coordinated bulk restart with dependency-aware sequencing. Defined at [lines 1686–1735](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/mcp_main.py#L1686).

## Implementation Architecture

Each service lifecycle operation follows a four-phase execution pattern implemented in [`mcp_main.py`](https://github.com/call518/mcp-ambari-api/blob/main/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

```python
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

```python
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

```python
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`](https://github.com/call518/mcp-ambari-api/blob/main/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](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/mcp_main.py) |
| **[`src/mcp_ambari_api/functions.py`](https://github.com/call518/mcp-ambari-api/blob/main/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](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/functions.py) |
| **[`src/mcp_ambari_api/__init__.py`](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/__init__.py)** | Registers the FastMCP instance and enables tool discovery for MCP clients. | [View source](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/__init__.py) |

## 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`](https://github.com/call518/mcp-ambari-api/blob/main/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`](https://github.com/call518/mcp-ambari-api/blob/main/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`](https://github.com/call518/mcp-ambari-api/blob/main/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.