Diagnoses Postgres logical replication: slot WAL retention, walsender lag, stuck subscriptions, with gated remediation.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@pg-logical-mcp check replication slots health"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Diagnose Postgres logical replication: slot WAL retention, walsender lag, stuck subscriptions, with gated remediation.
An MCP server that lets an AI agent introspect and reason about a PostgreSQL logical replication / CDC setup — replication slots and WAL retention, walsender and decoding pressure, publications, subscriptions, and stuck-apply diagnosis — plus a small set of gated remediation tools.
It deliberately does not compete in the crowded "query optimizer / index advisor" MCP space. It targets the replication/CDC layer, which is largely untooled and where a lot of real production incidents come from.
Two layers, explicitly separated:
Deterministic tools return raw catalog/stats state. They keep the agent
grounded in facts and are individually testable. (list_replication_slots,
inspect_walsenders, decoding_stats, list_publications,
inspect_subscriptions, subscription_errors, peek_changes.)
Judgment tools synthesise that state into "here's what's wrong and what
you can do." This is where the reasoning earns its place. (assess_slot_risk,
check_publication_coverage, diagnose_stuck_subscription.)
Dangerous operations sit behind deterministic guardrails: the model can recommend a slot drop or a transaction skip, but is structurally prevented from fat-fingering a data-losing operation. This is the same deterministic-gate-plus-judgment split used in the companion pre-commit-review hook — the two pieces read as one coherent point of view: let the model reason, but put the irreversible levers behind a deterministic lock it cannot pick.
The judgment logic lives in diagnostics.py as pure functions over provider
output, so it is unit-tested with no live database (tests/test_diagnostics.py).
Related MCP server: postgres-mcp-server
list_replication_slots (deterministic) — pg_replication_slots plus WAL pinned per slot, wal_status, safe_wal_size, active state, holding pid.
assess_slot_risk (judgment) — samples the WAL generation rate and, against max_slot_wal_keep_size, projects which slot is closest to invalidation and a rough time-to-invalidation / time-to-disk-fill. The differentiated diagnostic no incumbent does.
inspect_walsenders (deterministic) — pg_stat_replication: state, write/flush/replay lag (intervals and LSN diffs), sync_state.
decoding_stats (deterministic) — pg_stat_replication_slots: spill_txns/spill_bytes and streaming stats. Surfaces large-transaction decode spill, a real, obscure slowness cause.
list_publications (deterministic) — pg_publication / pg_publication_tables with row filters, column lists, published operations.
check_publication_coverage (judgment) — flags the two silent failures: a table never added to the publication, and a published table whose REPLICA IDENTITY won't support UPDATE/DELETE. Both lose data quietly rather than erroring.
inspect_subscriptions (deterministic) — pg_subscription joined with pg_stat_subscription. The connection string is omitted (it holds a password).
subscription_errors (deterministic) — pg_stat_subscription_stats apply/sync error counts.
diagnose_stuck_subscription (judgment, marquee) — correlates error state with the LSN apply is wedged at, explains why apply is blocked (typically a unique-constraint conflict on the subscriber), and lays out the two real options: resolve the conflicting row, or skip the offending transaction.
peek_changes (deterministic) — wraps pg_logical_slot_peek_changes (the peek variant, not get), so inspecting the queue does not consume it or advance the slot.
advance_slot, skip_apply_transaction, drop_slot — each mutates irreversible state. Every one:
is read-only unless the server was started with PG_LOGICAL_MCP_ALLOW_WRITES set and the call passes allow_writes=true (a two-key gate the model can't fully turn on its own);
requires the exact slot name / subscription name and the exact LSN — there is no "advance to latest" / "skip to head" convenience that silently discards an unknown amount of data;
returns a dry-run preview before it will execute.
Published to PyPI; run it with uvx or pipx — no clone required:
// MCP client config — one entry per node you want to inspect.
{
"mcpServers": {
"pg-publisher": {
"command": "uvx",
"args": ["pg-logical-mcp"],
"env": { "PG_LOGICAL_MCP_DSN": "host=publisher.internal port=5432 user=replmon dbname=appdb" }
},
"pg-subscriber": {
"command": "uvx",
"args": ["pg-logical-mcp"],
"env": { "PG_LOGICAL_MCP_DSN": "host=subscriber.internal port=5432 user=replmon dbname=appdb" }
}
}
}Each server points at one node. Slots/walsenders/publications live on the
publisher; subscriptions live on the subscriber — so to see both sides, add both
entries. Connection details come from PG_LOGICAL_MCP_DSN (or the standard
PG* libpq env vars). Provide the password via .pgpass or PGPASSWORD rather
than embedding it where it might be logged.
To enable the remediation tools, add "PG_LOGICAL_MCP_ALLOW_WRITES": "1" to that
server's env. Leave it unset and the server is strictly read-only.
Reading pg_subscription and the subscription stats views needs elevated
privileges. The demo containers run as the postgres superuser for simplicity.
Production use should use a deliberately scoped role, not superuser — grant
only what the tools read (pg_monitor covers most stats views; reading
pg_subscription and using the replication functions needs more). Treat the
remediation tools as privileged operations and gate them at the role level too,
not just with PG_LOGICAL_MCP_ALLOW_WRITES.
The author hosts nothing. This ships as a local subprocess your MCP client launches over stdio. This tool needs elevated privileges and a path into the replication subsystem — often in production. A hosted model would mean the author holding your credentials and a route into your production database: unacceptable exposure for everyone. Local means the author never touches a credential or a customer database. If your team later wants a shared deployment, MCP's HTTP transport lets you self-host it near your own database — your deployment decision, not a hosted service.
Local containers, no infrastructure of your own touched:
docker compose -f docker/docker-compose.yml up -d # publisher :5433, subscriber :5434
# Scenario 1 — wedge a subscription on a primary-key conflict
python scenarios/stuck_subscription.py
# then ask the agent: run diagnose_stuck_subscription against the subscriber
# Scenario 2 — pin a growing pile of WAL behind an inactive slot
python scenarios/slot_retention.py
# then ask the agent: run assess_slot_risk against the publisher
python scenarios/slot_retention.py --recover # restart subscriber, drain the slotPoint the MCP client's pg-publisher entry at host=localhost port=5433 and
pg-subscriber at host=localhost port=5434 (user/password postgres, db
appdb) to drive the tools against the demo.
uv venv && uv pip install -e ".[dev]"
pytest # exercises the pure judgment layer, no DB neededSee CLAUDE.md for architecture and conventions.
GPL-3.0-or-later. See LICENSE.
Advance a replication slot to an EXPLICIT LSN (irreversible).
Moves the slot's confirmed position forward, discarding all changes
before to_lsn. You must pass the exact slot name and target LSN — there
is no advance-to-latest shortcut. Dry-run unless allow_writes=true AND
the server was started with PG_LOGICAL_MCP_ALLOW_WRITES set.
| Name | Required | Description | Default |
|---|---|---|---|
| to_lsn | Yes | ||
| slot_name | Yes | ||
| allow_writes | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses irreversibility, discarding changes before to_lsn, dry-run behavior, and the environmental prerequisite. This provides sufficient transparency for safe use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences convey the purpose, irreversibility, parameter requirements, and dry-run behavior without redundant information. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the three parameters and presence of an output schema, the description covers all essential behavioral and usage aspects: slot advancement, irreversibility, LSN specification, and write safeguards. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds full meaning: slot_name and to_lsn are identified as 'exact slot name and target LSN', and allow_writes is explained with dry-run logic. All parameters are covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Advance a replication slot to an EXPLICIT LSN (irreversible)' with a clear verb and resource. It distinguishes from siblings like 'drop_slot' and 'peek_changes' by specifying the slot advancement action and explicit LSN requirement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains that the exact slot name and target LSN are required, and dry-run is the default unless allow_writes=true and the server variable is set. While it doesn't explicitly mention when not to use or alternatives, the context is clear for a focused tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Project which slot is closest to invalidation, and how soon.
Judgment tool. Samples the current WAL generation rate (reads pg_current_wal_lsn() twice, sample_interval_seconds apart), reads max_slot_wal_keep_size, and projects a rough time-to-invalidation per slot. Pass available_disk_bytes to also get a time-to-disk-fill estimate. Run this on the PUBLISHER.
| Name | Required | Description | Default |
|---|---|---|---|
| available_disk_bytes | No | ||
| sample_interval_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully explains the tool's behavior: it samples pg_current_wal_lsn() twice, reads max_slot_wal_keep_size, and projects estimates. It calls itself a 'Judgment tool,' implying estimates rather than exact counts. No side effects are mentioned, but it appears read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences), each sentence provides essential information: purpose, methodology, optional parameter, and execution context. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown), the description need not detail return values. It covers algorithm, parameters, and execution context (publisher). Could mention prerequisites but overall adequate for a judgment tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description adds meaning: it explains 'available_disk_bytes' is for disk-fill estimate and 'sample_interval_seconds' is the time between samples. This adds value beyond the schema's type-only definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Project which slot is closest to invalidation, and how soon.' It specifies the resource (replication slots) and the action (assess risk/invalidation), distinguishing it from siblings like list_replication_slots and drop_slot.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context: it's a 'Judgment tool' that samples WAL generation, reads max_slot_wal_keep_size, and projects time-to-invalidation. It notes to run on the PUBLISHER and explains the optional parameter for disk-fill estimate. However, it does not explicitly state when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cross-check published tables against an expected set.
Judgment tool. Flags the two silent failures that lose data without erroring: (1) an expected table that no publication carries, and (2) a published table whose REPLICA IDENTITY can't support UPDATE/DELETE (REPLICA IDENTITY NOTHING, or DEFAULT with no primary key). Pass expected_tables as "schema.table" strings (bare names assume public). Run this on the PUBLISHER.
| Name | Required | Description | Default |
|---|---|---|---|
| expected_tables | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It details the two specific silent failures checked and mentions REPLICA IDENTITY conditions. It does not explicitly state it is read-only, but given the 'check' nature, that is likely safe. A small gap is not mentioning any potential side-effects or permissions needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with short paragraphs, but the first sentence could be more concise. The bullet points in the second sentence are clear. Minor redundancy: 'Judgment tool.' could be integrated into the first line. Still efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single parameter, no annotations, and the presence of an output schema, the description covers the tool's purpose, usage context, parameter format, and behavioral details. The output schema handles return values, so no further explanation needed. Complete for a check tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'expected_tables' has zero description coverage in the input schema. The description fully compensates by explaining the format ('schema.table' strings) and default schema assumption (public). This adds essential meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'judgment tool' that cross-checks published tables against an expected set, and explicitly describes the two silent failures it catches. This differentiates it from sibling tools like list_publications which just list publications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells the agent to 'Run this on the PUBLISHER' and explains the expected format for expected_tables ('schema.table' strings, bare names assume public). It also provides context for when to use it (to catch silent data loss) and implicitly when not to use it (not for listing or other checks).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report logical-decoding spill/stream stats per slot.
Deterministic. Reads pg_stat_replication_slots for spill_txns / spill_bytes and streaming stats. Large spill_bytes means big transactions are spilling decode work to disk — an obscure but real cause of replication slowness (e.g. outbox batches that decode badly). Run this on the PUBLISHER.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses behavior: 'Deterministic. Reads pg_stat_replication_slots for spill_txns / spill_bytes and streaming stats.' Clearly indicates read-only nature and no side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with purpose, then behavioral details, then usage context. No wasted words, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, read-only), description fully covers what, how, and why. Output schema exists, so return value details are not required. Complete for the task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100% trivially. Description adds no param info, but baseline for 0 parameters is 4 per instructions. No need for additional detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Report logical-decoding spill/stream stats per slot', specifying the resource and action. Distinguishes from siblings like list_replication_slots by focusing on spill/stream metrics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Run this on the PUBLISHER' and provides troubleshooting context (large spill_bytes cause replication slowness). Does not explicitly mention when not to use it or list alternatives, but context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explain why apply is wedged and lay out the two real fixes.
Judgment tool (the marquee one). Correlates subscription error state with the LSN apply is stuck at, explains the usual cause (a unique/primary-key conflict on the subscriber), and presents the two options: resolve the conflicting row, or skip the offending transaction. Points you at the subscriber server log for the exact conflicting row. Run this on the SUBSCRIBER.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool correlates subscription error state with LSN, explains the usual cause (unique/primary-key conflict), specifies two options (resolve conflicting row or skip transaction), and mentions pointing to subscriber server log. This is highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences plus two line items. Every sentence adds value, and the most critical information is front-loaded ('Explain why apply is wedged'). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, no annotations, but presence of an output schema, the description fully explains the tool's behavior and output. It covers cause, symptoms, fixes, and log reference, making it complete for an agent to understand.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema covers everything. The description adds context beyond the schema by detailing what the tool does and how it works. Baseline 4 is appropriate as no parameters need explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Explain why apply is wedged and lay out the two real fixes.' It specifies the resource (stuck subscription) and action (diagnose), and distinguishes itself from sibling tools like skip_apply_transaction by calling itself a 'judgment tool'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Run this on the SUBSCRIBER.' It implies use when apply is wedged, but does not explicitly list when not to use or compare with all alternatives. However, it contrasts with sibling tools by being a judgment tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Drop a replication slot by EXACT name (irreversible).
Removes the slot and releases the WAL it pins. Any subscriber relying on it can no longer resume and must be re-created and re-synced. You must pass the exact slot name. Dry-run unless allow_writes=true AND PG_LOGICAL_MCP_ALLOW_WRITES is set.
| Name | Required | Description | Default |
|---|---|---|---|
| slot_name | Yes | ||
| allow_writes | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses irreversibility, WAL release, subscriber impact, and dry-run guard, giving comprehensive behavioral insight beyond schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loading key points (exact name, irreversibility). Every sentence adds essential information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers behavior, guard condition, and outcome for subscribers. Lacks explicit mention of prerequisites (e.g., slot exists) or error handling, but is otherwise complete for a simple drop tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds meaning: slot_name must be exact name, allow_writes controls dry-run. Could further detail slot_name origins or allow_writes format, but current info is useful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool drops a replication slot by exact name and emphasizes irreversibility. It distinguishes from siblings like list_replication_slots and advance_slot by specifying the destructive exact-name operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: irreversible, dry-run unless allow_writes=true and env var set. Does not explicitly mention when not to use or suggest alternatives, but siblings imply other tools for different operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect subscriptions and their apply-lag signals.
Deterministic. Joins pg_subscription with pg_stat_subscription for worker state, received/latest-end LSNs, and apply-lag signals (last_msg_send_time vs last_msg_receipt_time). The connection string (subconninfo) is deliberately omitted — it holds a password. Reading pg_subscription needs elevated privileges. Run this on the SUBSCRIBER.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description fully discloses behavioral traits: deterministic (read-only), omitted connection string for password security, required privileges, and the data it returns (worker state, LSNs, apply-lag signals).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (5 lines) and front-loaded with the purpose. Every sentence adds value: deterministic, joins, omitted field, privileges, where to run.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description mentions key output columns (worker state, LSNs, apply-lag signals) without listing every field. It also addresses security. This is sufficient, but could explicitly reference the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the description adds no parameter details. Given zero parameters, the baseline is 4, and the description does not need to add more.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inspects subscriptions and their apply-lag signals, specifying the resources pg_subscription and pg_stat_subscription. It distinguishes from siblings like diagnose_stuck_subscription or subscription_errors by being a general inspection tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by noting that it must be run on the subscriber and requires elevated privileges. However, it does not explicitly state when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect active walsender connections and their lag.
Deterministic. Reads pg_stat_replication: per-connection state, write/flush/replay lag (both as time intervals and as LSN byte diffs from sent_lsn), and sync_state. Run this on the PUBLISHER.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It correctly describes the tool as deterministic and read-only, and lists the specific data it retrieves. It does not mention any potential impacts or authorization needs, but these are minimal for a read-only system view query.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, front-loaded with the main purpose, followed by details. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema is present, the description provides all necessary context: what it does, what it reads, where to run it, and its deterministic nature. It is complete for a monitoring tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters (schema coverage 100%), so the baseline is 4. The description adds value by explaining what is inspected, compensating for the lack of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inspects active walsender connections and their lag. It specifies the exact fields and source (pg_stat_replication). The verb 'inspect' combined with the resource 'walsender connections' is specific and distinct from sibling tools like advance_slot or diagnose_stuck_subscription.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it should be run on the PUBLISHER, is deterministic, and reads a system view. However, it does not explicitly exclude when not to use or mention alternatives among siblings. This is a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List publications and the tables each carries.
Deterministic. Enumerates pg_publication and pg_publication_tables with per-table column lists, row filters (PG15+), and the published operations (insert/update/delete/truncate). Run this on the PUBLISHER.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes as 'Deterministic' and enumerates the output details (per-table column lists, row filters, operations). With no annotations, the description carries the full burden; it implies read-only behavior but does not explicitly state safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no wasted words. Every sentence provides essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema exists, the description sufficiently covers the listing task. It could mention that it is a safe read operation, but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. The description adds value by explaining what information is listed, which goes beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'List publications and the tables each carries', which is a specific verb+resource. Distinguishes from siblings like 'check_publication_coverage' and 'inspect_subscriptions' by detailing the contents (tables, columns, filters, operations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Advises to 'Run this on the PUBLISHER', providing location guidance. However, it does not explicitly compare to alternatives or state when not to use, missing opportunities for clearer decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List replication slots with the WAL each one pins.
Deterministic. Wraps pg_replication_slots and joins in the bytes of WAL held per slot (pg_current_wal_lsn() - restart_lsn), wal_status (reserved/extended/unreserved/lost), safe_wal_size, active state and the holding pid. Run this on the PUBLISHER.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states determinism, wraps specific functions, and lists returned fields. It does not explicitly declare read-only but implies it by listing rather than mutating.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is three sentences, front-loaded with the core purpose, and every sentence adds value (purpose, implementation details, execution location). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema (not shown but present), the description covers what the agent needs: what it does, where to run, and key output details. Could mention it is safe/read-only, but not a critical omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. The description does not need to add parameter semantics; a baseline score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists replication slots with specific WAL information, including fields like wal_status, active state, and holding pid. It distinguishes itself from sibling tools like drop_slot or advance_slot by focusing on listing and diagnostics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs 'Run this on the PUBLISHER', providing clear usage context. It does not explicitly mention when not to use it or alternatives, but for a list tool this suffices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Peek at pending changes in a slot WITHOUT consuming them.
Deterministic. Wraps pg_logical_slot_peek_changes — the peek variant,
not get — so inspecting the queue does not advance the slot or consume
the changes. Returns up to limit rows of (lsn, xid, data). The data
rendering depends on the slot's output plugin: text for test_decoding,
binary for pgoutput. Run this on the PUBLISHER.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| slot_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description fully discloses behavior: deterministic, wraps pg_logical_slot_peek_changes (peek variant), does not advance slot, returns up to limit rows, data rendering depends on output plugin, and deployment on publisher.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, no wasted words. Each sentence adds unique value: purpose, determinism+function, return format+deployment.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description still explains return structure (lsn, xid, data) and dependencies. Covers all key aspects for a peek tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has no descriptions (0% coverage). Description adds meaning by explaining 'limit' (up to limit rows, default 20) and implies slot_name via context. Could be more explicit about slot_name but sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Peek' and resource 'pending changes in a slot', and specifies it does not consume changes. It distinguishes from siblings like 'advance_slot' and 'drop_slot' by focusing on non-destructive inspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to run on the publisher and clarifies that peeking does not advance the slot or consume changes. While no explicit when-not or alternatives among siblings, the context is sufficient for correct use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Skip the transaction wedging a subscription at an EXPLICIT LSN.
Issues ALTER SUBSCRIPTION ... SKIP (lsn = ...) so the apply worker steps over the offending transaction. That transaction's changes are discarded PERMANENTLY — use only when you've confirmed (from the subscriber log) that the change is genuinely redundant. Pass the exact LSN from diagnose_stuck_subscription; there is no skip-to-head shortcut. Dry-run unless allow_writes=true AND PG_LOGICAL_MCP_ALLOW_WRITES is set.
| Name | Required | Description | Default |
|---|---|---|---|
| lsn | Yes | ||
| allow_writes | No | ||
| subscription_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses permanent discard of changes, the dry-run behavior, and the guard (allow_writes and env var). However, it omits changes in behavior on error (e.g., invalid LSN) or permission requirements, which are important for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no filler. It front-loads the main action, then explains the risk and the usage conditions. Every sentence adds value, making it efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and 3 parameters with 0% schema coverage, the description covers the essential behavioral context (permanent discard, dry-run, dependency on diagnose_stuck_subscription). It lacks mention of required privileges or failure modes, but the presence of an output schema (not shown) reduces the need to describe return values. Overall, it's nearly complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains lsn as the exact LSN from diagnose_stuck_subscription, subscription_name by context, and allow_writes as the dry-run toggle. It adds practical meaning beyond the schema's bare types, though the LSN format could be more explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'skips the transaction wedging a subscription at an EXPLICIT LSN' and specifies the SQL command ALTER SUBSCRIPTION ... SKIP. It clearly identifies the action (skip), the resource (subscription at a specific LSN), and distinguishes from sibling tools like diagnose_stuck_subscription by referencing it as the source for the LSN.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong usage context: use only when the change is confirmed as redundant from the subscriber log, pass the exact LSN from diagnose_stuck_subscription, and no skip-to-head shortcut. It implies dry-run unless allow_writes is set, but lacks explicit when-not-to-use cases (e.g., if subscription is not stuck).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report apply and tablesync error counts per subscription.
Deterministic. Reads pg_stat_subscription_stats (PG15+) for apply_error_count and sync_error_count. A non-zero apply_error_count is the first sign of a wedged subscription. Run this on the SUBSCRIBER.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it reads pg_stat_subscription_stats, is deterministic, and runs on the subscriber. Notes that non-zero apply_error_count indicates a wedged subscription. No annotations provided, so description carries full burden; additionally stating that it's read-only and has no side effects would raise this to 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: three short sentences cover purpose, characteristics, data source, practical significance, and run location. Every sentence adds unique value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with zero parameters and an output schema, the description fully covers purpose, source, location, and interpretation of results. Nothing essential is missing given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so description adds no param-specific info, but that's appropriate (baseline 4). The description focuses on the tool's function and output, which is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reports apply and tablesync error counts per subscription, names the specific system view (pg_stat_subscription_stats), and distinguishes from siblings by focusing on error counts. The verb 'report' and resource 'error counts' are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: run on the SUBSCRIBER, deterministic, reads PG15+ stats, and hints at use case (first sign of wedged subscription). Lacks explicit comparisons to siblings or when-not-to-use, but the sibling set suggests alternative diagnostics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0advance_slotassess_slot_riskcheck_publication_coveragedecoding_statsdiagnose_stuck_subscriptiondrop_slotinspect_subscriptionsinspect_walsenderslist_publicationslist_replication_slotspeek_changesskip_apply_transactionsubscription_errorsEach tool has a well-defined, distinct purpose in logical replication management. There is no functional overlap; tools like advance_slot and skip_apply_transaction operate on different mechanisms despite both involving LSNs.
All tool names follow a consistent lowercase_underscore verb_noun pattern (e.g., advance_slot, inspect_subscriptions, list_publications), making them predictable and easy to differentiate.
With 13 tools, the set is well-scoped for logical replication diagnostics and management. Each tool addresses a specific operation without unnecessary redundancy or bloat.
The tools cover essential lifecycle operations (list, peek, advance, drop slots; inspect subscribers; diagnose issues) and include risk assessment. Missing create/alter subscription or publication creation, but those may be out of scope for a diagnostic-focused server.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Comprehensive PostgreSQL documentation and best practices, including ecosystem tools
Hosted MCP server for PostgreSQL diagnostics: slow queries, missing indexes, connection pressure.
Deterministic safety, correctness & cost gate that vets Postgres SQL before your AI agent runs it.
Generate, fix, explain and run read-only SQL on PostgreSQL, MySQL and SQL Server
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/esauro/pg-logical-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
