# How to Monitor PostgreSQL Replication Status Using MCP Server Tools

> Easily monitor PostgreSQL replication status with the get_replication_status tool from call518/mcp-postgresql-ops. Get a unified report of key metrics for reliable performance.

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

---

**The `get_replication_status` tool in the call518/mcp-postgresql-ops repository automatically aggregates `pg_stat_replication`, replication slots, and WAL receiver metrics into a single, version-aware report to monitor PostgreSQL replication status.**

The call518/mcp-postgresql-ops MCP server provides a dedicated tool to monitor PostgreSQL replication status without manual SQL scripting. It handles version compatibility transparently, supporting PostgreSQL 12 through 17, and returns formatted results via HTTP API or LLM chat interfaces.

## How the Replication Monitoring Tool Works

The `get_replication_status` tool operates as a registered FastMCP coroutine that executes three complementary system catalog queries. Located in [`src/mcp_postgresql_ops/mcp_main.py`](https://github.com/call518/mcp-postgresql-ops/blob/main/src/mcp_postgresql_ops/mcp_main.py) (lines 315-395), this function orchestrates data collection from both primary and standby perspectives.

### Version-Aware Query Generation

The tool leverages the `VersionAwareQueries` class in [`src/mcp_postgresql_ops/version_compat.py`](https://github.com/call518/mcp-postgresql-ops/blob/main/src/mcp_postgresql_ops/version_compat.py) to adapt SQL syntax based on your PostgreSQL version:

- **Replication slots**: `get_replication_slots_query()` (lines 308-352) includes `wal_status` and `safe_wal_size` columns when running PostgreSQL 13 or higher.
- **WAL receiver**: `get_wal_receiver_query()` (lines 554-600) adds `written_lsn` and `flushed_lsn` metrics for PostgreSQL 16+.

The helper function `get_postgresql_version()` detects the server version automatically, ensuring the tool executes compatible SQL without manual configuration.

### Data Aggregation and Formatting

After building the queries, the tool calls `execute_query()` from [`src/mcp_postgresql_ops/functions.py`](https://github.com/call518/mcp-postgresql-ops/blob/main/src/mcp_postgresql_ops/functions.py) (lines 58-80) to run SQL against the configured instance. It retrieves data from:

1. **pg_stat_replication** – Active WAL sender processes on the primary
2. **Replication slots** – Logical and physical slot status
3. **WAL receiver** – Standby-side receiver process state

The raw results pass through `format_table_data()` to generate human-readable tables. If a query returns no rows (for example, querying `pg_stat_replication` on a standby), the tool displays a contextual message explaining the absence of data.

## Calling the get_replication_status Tool

You can invoke the tool through three primary interfaces, all exposing the same underlying functionality defined in [`mcp_main.py`](https://github.com/call518/mcp-postgresql-ops/blob/main/mcp_main.py).

### Via HTTP API

The MCP server exposes a Swagger UI at `http://<host>:8003/docs`. Send a POST request to the `/postgresql-ops` endpoint with the tool name:

```bash
curl -X POST http://localhost:8003/postgresql-ops \
  -H "Content-Type: application/json" \
  -d '{"tool":"get_replication_status"}'

```

The response returns a plain-text block containing three formatted sections: replication connections, slot information, and WAL receiver status.

### Via OpenWebUI or LLM Chat

Register the MCP server URL in your LLM client (e.g., OpenWebUI under **Settings → Tools**). Once configured, ask:

> "Show me the replication status of my PostgreSQL cluster."

The LLM invokes `get_replication_status` automatically and renders the formatted output in the conversation thread.

### Programmatically

Integrate the tool into Python applications using `httpx` or `requests`:

```python
import httpx

url = "http://localhost:8003/postgresql-ops"
payload = {"tool": "get_replication_status"}

resp = httpx.post(url, json=payload)
print(resp.text)

```

This returns the same formatted report available through the web interface.

## Understanding the Output

The tool returns three distinct sections that cover both primary and standby perspectives:

- **Replication Connections (Primary Side)**: Displays `client_addr`, `usename`, `application_name`, `state`, and lag metrics (`write_lag`, `flush_lag`, `replay_lag`). These columns show how far behind each standby server is in applying WAL.
- **Replication Slots**: Lists `slot_name`, `active` state, `restart_lsn`, and `confirmed_flush_lsn`. On PostgreSQL 13+, you also see `wal_status` (indicating `reserve` or `unreserved` state) and `safe_wal_size_mb`.
- **WAL Receiver Status (Standby Side)**: Shows the receiver process ID, `status`, `receive_start_lsn`, and on PostgreSQL 16+, `written_lsn` and `flushed_lsn` for precise lag measurement.

The connection parameters derive from environment variables defined in [`src/mcp_postgresql_ops/functions.py`](https://github.com/call518/mcp-postgresql-ops/blob/main/src/mcp_postgresql_ops/functions.py) under `POSTGRES_CONFIG` (e.g., `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_DB`).

## Summary

- The `get_replication_status` tool in call518/mcp-postgresql-ops consolidates replication monitoring into a single RPC call.
- It automatically adapts queries for PostgreSQL versions 12 through 17 using `VersionAwareQueries` in [`version_compat.py`](https://github.com/call518/mcp-postgresql-ops/blob/main/version_compat.py).
- The tool queries `pg_stat_replication`, replication slots, and WAL receiver status via `execute_query()` in [`functions.py`](https://github.com/call518/mcp-postgresql-ops/blob/main/functions.py).
- Results are accessible via HTTP POST to `/postgresql-ops`, OpenWebUI chat, or direct Python HTTP clients.
- Output includes lag metrics, slot activity, and receiver state with version-specific columns like `wal_status` (PG 13+) and `written_lsn` (PG 16+).

## Frequently Asked Questions

### What PostgreSQL versions does the replication monitoring tool support?

The tool supports PostgreSQL 12 through 17. The `VersionAwareQueries` class in [`src/mcp_postgresql_ops/version_compat.py`](https://github.com/call518/mcp-postgresql-ops/blob/main/src/mcp_postgresql_ops/version_compat.py) automatically detects your server version via `get_postgresql_version()` and adjusts the column lists accordingly, ensuring compatibility without manual intervention.

### Why do I see "No active replication connections found" when running the tool?

This message appears when querying `pg_stat_replication` on a standby server or when no replicas are currently connected. The primary server maintains `pg_stat_replication` entries only when active WAL sender processes exist; standbys return empty results for this view, which the tool handles gracefully with explanatory text.

### How does the tool handle authentication with the PostgreSQL instance?

Authentication uses environment variables defined in [`src/mcp_postgresql_ops/functions.py`](https://github.com/call518/mcp-postgresql-ops/blob/main/src/mcp_postgresql_ops/functions.py) within the `POSTGRES_CONFIG` dictionary. Set `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_DB`, `POSTGRES_USER`, and `POSTGRES_PASSWORD` before starting the MCP server. The `execute_query()` function reads these values to establish the database connection.

### Can I monitor logical replication slots separately from physical streaming replication?

Yes. The `get_replication_status` tool queries all replication slots via the version-aware slot query in [`version_compat.py`](https://github.com/call518/mcp-postgresql-ops/blob/main/version_compat.py). The output includes a `slot_type` column distinguishing `logical` from `physical` slots, along with plugin names for logical slots and activity status for both types.