Consul cluster_backend plugin for MCPG gateway providing distributed coordination via Consul's catalog, events, sessions, and KV APIs
Strong foundation with 15 well-named tools following verb_noun convention (acquire_leadership, kv_put, lease_renew). All tools have descriptions (avg 180 chars, within 10-1024 baseline). Input schemas present for all tools with typed parameters. However, output schemas are not documented, LLMs cannot predict return structures. Parameter descriptions are present but terse (avg 45 chars vs 72 baseline). Missing error recovery guidance and confirmation patterns for destructive operations (kv_delete, lease_release). No tool annotations (readOnlyHint, destructiveHint) despite clear risk classifications in metadata.
Acquire a distributed leadership lease via Consul Sessions API + KV CAS. Returns fencing token (KV LockIndex) and expiry time. Background renewal task fires every ttl × (1 - renew_pct/100)
Acquire a distributed lock via Consul Sessions API + KV CAS. Returns fencing token (KV LockIndex) and expiry time. Background renewal task fires every ttl × (1 - renew_pct/100)
DELETE /v1/kv/<key> - remove a key from Consul KV. Probes first to honor the Ok(false) when absent contract. Logically-expired keys count as already-absent
GET /v1/kv/<key> - retrieve a value from Consul KV. Decodes logical TTL envelope and returns None if logically expired (lazy expiry)
GET /v1/kv/<prefix>?recurse - list all keys under a prefix. Decodes logical TTL envelopes and filters out logically-expired entries (lazy expiry)
PUT /v1/kv/<key> - unconditional last-writer-wins write to Consul KV. Wraps value in logical TTL envelope if ttl is specified
Output schemas not documented. LLMs cannot predict return structures for any tool. Responses like PublishedMessages, LeaseExpired, CatalogServiceEntry are mentioned in descriptions but not formally specified.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk classifications. Destructive tools (kv_delete) and write operations lack machine-readable hints for agent safety.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 56 | <=2025-11-25 | v2 |
PUT /v1/kv/<key>?cas=0 - atomic create-only write. Single-winner across replicas. Treats logically-expired keys as absent and reclaims them via CAS overwrite
Release an active lease via kv_release(key, session_id) + session_destroy(session_id). Idempotent via AtomicBool; background renewal task aborts on drop
Extend an active lease's TTL via session_renew. Returns LeaseExpired if Consul reports the session as gone (404 / empty array body)
GET /v1/catalog/service/<name> returns every healthy gateway instance registered with the Consul catalog
Reports this gateway instance's identity from operator config + agent metadata
PUT /v1/event/fire/<topic> - publish event payload to the Consul-cluster gossip layer. Best-effort delivery via Consul's gossip layer. Wraps payload in versioned envelope to carry routing key metadata
Long-poll GET /v1/event/list with ?index= blocking semantics. Decodes envelope, drops malformed events, applies exact-match routing-key filter when supplied. Returns stream of PublishedMessages
Non-blocking acquire of a distributed lock. Returns Ok(None) when the backend reports the lock is held by another session
Long-poll on the catalog index. Diffs each successive snapshot against the previous one and emits Joined/Left events. Stream lives until cancelled
Destructive operations lack confirmation/dry-run patterns. kv_delete and lease_release are irreversible but offer no confirmation step or dry-run mode to prevent agent mistakes.
Error recovery guidance missing. Descriptions mention error cases (LeaseExpired, lock held by another session) but do not guide LLM on recovery actions or retry strategies.
Parameter descriptions are terse (avg 45 chars vs 72 baseline). Examples: 'Opaque lease handle from acquire' lacks format/constraint details. 'Event topic name' does not explain naming rules or length limits.