An AI assistant investigating consumer lag needs evidence: routes, queue progress, connections, and Broker health. Giving it permission to reset offsets or change Broker configuration is a separate operational decision.
RocketMQ-Rust, an independent community implementation of Apache RocketMQ in Rust, makes that distinction concrete in its Model Context Protocol (MCP) services. The query service gathers context. The control service exposes a small set of typed changes with separate authorization, planning, and audit rules.
This walkthrough follows the repository at commit 3017655, inspected on November 7, 2026. It describes the checked-in design, not a benchmark or a report of production testing.
1. One entrypoint, two separate server modes
The rocketmq-mcp package is a feature-composed entrypoint. Its defaults are read-only, diagnose, and stdio; read-only is a compatibility alias for query.
At startup, ROCKETMQ_MCP_MODE selects exactly one server:
-
query, the default, launches the diagnostics service. -
controllaunches the separately configured HTTPS control service.
Selecting a mode that was not compiled fails before startup. Compiling write-tools does not turn query mode into a write-capable tool catalog. The launcher implementation delegates to the selected server's own entrypoint and runtime.
There is a useful deployment caveat here. A binary built with both query and write features contains both sides of the shared Admin dependency. If you require separate compiled dependency sets, deploy the standalone rocketmq-mcp-query and rocketmq-mcp-control binaries. Separate tool catalogs and separate dependency sets are different guarantees.
2. Diagnosis returns evidence with limits
The query service exposes tools such as:
rocketmq_get_consumer_lagrocketmq_diagnose_consumer_lagrocketmq_get_broker_diagnosticsrocketmq_diagnose_message_delivery
Its responses carry observation time, freshness, cache status, partial-result status, warnings, and typed data. Those fields matter when an assistant is explaining an incident. Cached evidence may be useful, but its age belongs in the explanation. A partial diagnosis should not be presented as a complete view of the cluster.
Message-delivery diagnosis does not return message bodies. Query output also passes through authorization, sanitization, and output bounds. These controls still need appropriate Broker permissions and deployment configuration; a read-only interface can expose operational information.
For local exploration, the documented default entrypoint is:
cd rocketmq-ai/rocketmq-mcp cargo run --locked It waits for MCP JSON-RPC requests on stdin. Without explicit configuration, it uses local-development settings for 127.0.0.1:9876; actual RocketMQ queries need a running NameServer and Broker. Production HTTP deployment has a different configuration and authentication path.
3. A compiled mutation tool still needs authority
The control service is deny-by-default. Its default build contains neither the Admin Core dependency nor production mutation tools. The optional write-tools feature adds nine reviewed operations, covering Topic and Consumer Group upserts, offset reset, a bounded Broker configuration patch, consumer request mode, Proxy drain begin/cancel, and temporary Broker log-level set/restore.
It exposes no general shell, arbitrary Admin command, or free-form RPC tool.
A mutation must pass several independent gates: authenticated write scope, permitted cluster, permitted operation, runtime enablement, and compiled/registered availability. The server and principal allowlists must agree. Control uses enforcing TLS and OAuth JWT verification; it has no stdio control transport.
Configuration starts with mutations_enabled = false and dry_run = true. An execution also requires confirm = true and a valid reason.
That confirmation field is an API requirement. By itself, it does not establish that a human reviewed the change. The workflow around the MCP client must supply the review and authorization appropriate to the environment.
4. Bind execution to the plan that was reviewed
A dry run can become stale while someone reads it. Another operator may change configuration, or a consumer may advance its offset.
The control tool reference addresses this with plan_digest. For example, an illustrative dry-run argument object for rocketmq_patch_broker_config is:
{ "schema_version": "rocketmq-mcp-control.arguments.v1", "cluster": "staging-a", "broker_name": "broker-a", "properties": { "traceTopicEnable": "true" }, "dry_run": true } The names here are placeholders for configured logical targets. This example has not been executed.
The dry run reports a digest of the requested change, observed state, and planned target results. To execute the reviewed plan, the caller sends the returned digest as expected_plan_digest, together with the execution arguments.
Execution performs its own preflight. If its plan differs, it writes nothing and returns precondition_conflict. The operator can then inspect a fresh dry run. A revised plan needs a new request key.
The digest is optional unless mutations.require_plan_digest = true. Without it, an authorized execution can act on the state its own preflight reads, which may differ from the earlier dry run.
A digest compares plans. It does not identify the reviewer or grant permission.
5. Persist the audit start before opening the Admin session
The control workflow requires a durable started audit record before creating a mutation session or performing RocketMQ RPC. If that record cannot be persisted, the call fails with audit_unavailable.
After admission, the workflow performs preflight, planning, optional execution, verification, bounded session shutdown, and terminal audit recording. The session supervisor belongs to the service runtime, so dropping the HTTP waiter does not simply discard an acquired session and its terminal audit work.
This ordering separates two important cases:
- Failure to record the start prevents the operation from reaching the cluster.
- Failure after a write may leave a changed cluster even if the caller receives an error.
Responses retain per-target evidence, including partial and verification failures. An HTTP success/failure summary alone is insufficient to decide whether a multi-target operation changed anything.
6. Recover an uncertain result before retrying
The control service includes rocketmq_get_mutation_result for the caller's own invocations. It can look up an invocation_id or a supplied request_key and report finished, in_progress, interrupted, or not_found.
An interrupted invocation has no recorded terminal outcome. A missing lookup result is not proof that no write happened. The lookup keeps bounded history, rebuilt from the active audit segment at startup.
Request-key deduplication is also bounded and process-local. Settled outcomes can be replayed for ten minutes, while failed or uncertain attempts require fresh preflight rather than a claim of universal exactly-once execution. There is no cross-restart cache guarantee.
For an integration test, deliberately lose a response after submitting a permitted change. Then verify that the client checks the result and current target state before deciding to retry. Run that experiment in a disposable environment.
What this design asks of an MCP client
A useful client integration should:
- Show observation freshness and partial evidence during diagnosis.
- Keep diagnostic access separate from authority to change the cluster.
- Present the exact dry-run targets and effects for review.
- Preserve the reviewed plan digest when executing.
- Read structured per-target outcomes and reconcile uncertainty before retrying.
RocketMQ-Rust makes these boundaries visible in configuration, Cargo features, schemas, and audit behavior. They provide concrete points to test when connecting an AI operations workflow to a messaging system.
The MCP entrypoint guide, query guide, and control tool reference are the best places to continue reading.
AI disclosure: This article was generated by AI from the linked public repository documentation and source. It does not claim firsthand deployment experience, executed examples, or performance measurements.
