mq9 MCP User Guide

Introduction

RobustMQ broker ships with built-in mq9 MCP support. Once the broker is running, any MCP-capable AI tool (Claude, Cursor, Cline, Hermes, etc.) can use mq9 for asynchronous Agent-to-Agent communication.

With mq9 MCP your Agent can:

Create its own mailbox to receive messages
Send messages to other Agents
Discover Agents with specific capabilities
Register itself so others can find it

This guide covers how to connect and use the tools. No broker-side configuration is needed — MCP is available the moment the broker starts.

Prerequisites

A running RobustMQ broker (HTTP service exposed on port 58080 by default)
An MCP-capable AI tool (Claude Desktop, Cursor, Cline, etc.)

If RobustMQ is not yet installed, refer to the RobustMQ installation documentation.

Quick Start

1. Confirm the broker is running

bash

robust-ctl cluster status

Confirm port 58080 is accessible:

bash

curl http://localhost:58080/health/node

2. Configure your AI tool

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

json

{
  "mcpServers": {
    "mq9": {
      "url": "http://localhost:58080/mcp"
    }
  }
}

Restart Claude Desktop.

Cursor

Edit .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (user-level):

json

{
  "mcpServers": {
    "mq9": {
      "url": "http://localhost:58080/mcp"
    }
  }
}

Cline / Continue / other HTTP MCP tools

Refer to each tool's MCP configuration documentation. The pattern is the same — set url to http://broker-host:58080/mcp.

3. Verify the connection

In Claude Desktop, type:

Create a mailbox called test.001 for me

If the response is successful, the connection is working.

stdio Mode

RobustMQ only exposes an HTTP MCP endpoint and does not support stdio.

If your AI tool only supports stdio (uncommon — most modern tools support HTTP), you can bridge using the community tool mcp-remote:

json

{
  "mcpServers": {
    "mq9": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:58080/mcp"]
    }
  }
}

mcp-remote is a community-maintained npm package that bridges any HTTP MCP server into stdio mode. RobustMQ does not provide a bridge command and does not maintain a stdio compatibility layer.

Tool List

mq9 MCP provides the following tools for LLM use:

Tool	Purpose
`mq9_create_mailbox`	Create a new mailbox
`mq9_send_message`	Send a message to a mailbox
`mq9_fetch_messages`	Fetch messages from a mailbox
`mq9_ack_message`	Acknowledge message processing
`mq9_query_mailbox`	Inspect messages in a mailbox (non-consuming)
`mq9_register_agent`	Register yourself in the mq9 registry
`mq9_discover_agents`	Find Agents with specific capabilities
`mq9_unregister_agent`	Deregister yourself

Parameters and typical usage for each tool follow.

Tool Reference

mq9_create_mailbox

Create a mailbox. The name must be lowercase and may contain letters, digits, and dots.

Parameters:

Parameter	Type	Required	Default	Description
`name`	string	No	auto-generated	Mailbox name (lowercase letters, digits, dots only). Broker generates one if omitted.
`ttl`	integer	No	broker default	Time-to-live in seconds
`desc`	string	No	—	Human-readable description

Example:

Create a mailbox called task.001.callback with a 1-hour TTL

LLM calls:

mq9_create_mailbox(name="task.001.callback", ttl=3600)

mq9_send_message

Send a message to a mailbox.

Parameters:

Parameter	Type	Required	Default	Description
`mail_address`	string	Yes	—	Destination mailbox address
`payload`	string	Yes	—	Message body (any string)
`priority`	string	No	`normal`	`normal` / `urgent` / `critical`

Example:

Send a message to agent.translator.inbox: 'Please translate this: Hello world'

LLM calls:

mq9_send_message(
  mail_address="agent.translator.inbox",
  payload="Please translate this: Hello world"
)

Urgent message:

Send an urgent message to agent.coordinator.inbox: 'System resources low, please pause all tasks'

LLM calls:

mq9_send_message(
  mail_address="agent.coordinator.inbox",
  payload="System resources low, please pause all tasks",
  priority="urgent"
)

mq9_fetch_messages

Fetch messages from a mailbox. Default behavior is to resume from the last acked position.

Parameters:

Parameter	Type	Required	Default	Description
`mail_address`	string	Yes	—	Mailbox address
`group_name`	string	Yes	—	Consumer group name. Use a stable identifier (e.g. your Agent ID). Each group maintains its own offset independently.
`max_messages`	integer	No	100	Maximum number of messages to return
`reset_to`	string	No	—	Override the consumer position (see below)

reset_to values:

Value	Behavior
omitted	Resume from the last acked position
`"earliest"`	Reset to the earliest message in the mailbox
`"latest"`	Skip history; receive only new messages
`"time:<unix_seconds>"`	Start from a specific timestamp, e.g. `"time:1746000000"`
`"id:<msg_id>"`	Start from a specific message (inclusive), e.g. `"id:42"`

Example:

Check my inbox for new messages

LLM calls:

mq9_fetch_messages(mail_address="claude.desktop.inbox", group_name="my-agent")

Read from the beginning:

Re-read all messages in claude.desktop.inbox from the start

LLM calls:

mq9_fetch_messages(mail_address="claude.desktop.inbox", group_name="my-agent", reset_to="earliest")

mq9_ack_message

Acknowledge that a message has been processed. After processing a message, call ack — the broker advances the consumer offset and the next fetch resumes from msg_id + 1.

Parameters:

Parameter	Type	Required	Default	Description
`mail_address`	string	Yes	—	Mailbox address
`group_name`	string	Yes	—	Consumer group name (must match the group used in fetch)
`msg_id`	integer	Yes	—	Message ID (from the fetch response)

Example:

(after fetching) I've finished processing that message, msg_id is 5

LLM calls:

mq9_ack_message(mail_address="claude.desktop.inbox", group_name="my-agent", msg_id=5)

mq9_query_mailbox

Inspect messages in a mailbox without affecting the consumer offset — pure read-only access.

Parameters:

Parameter	Type	Required	Default	Description
`mail_address`	string	Yes	—	Mailbox address
`key`	string	No	—	Filter by message key (exact match)
`tags`	string[]	No	—	Filter by tags; messages must carry all specified tags
`since`	integer	No	—	Unix timestamp (seconds); return only messages created after this time
`limit`	integer	No	20	Maximum number of messages to return

Example:

Peek at what's in task.001.callback without consuming anything

LLM calls:

mq9_query_mailbox(mail_address="task.001.callback")

Filter by tag:

Look for messages tagged 'billing' in agent.order.inbox

LLM calls:

mq9_query_mailbox(mail_address="agent.order.inbox", tags=["billing"])

mq9_register_agent

Parameters:

Parameter	Type	Required	Default	Description
`name`	string	Yes	—	Unique Agent name
`payload`	string	Yes	—	Capability description (plain text or an A2A AgentCard JSON serialized as a string)

Example:

Register me as a translation assistant capable of Chinese–English translation, inbox is agent.translator.inbox

LLM calls:

mq9_register_agent(
  name="translation-agent-001",
  payload="{\"capabilities\":[\"zh-en translation\"],\"inbox\":\"agent.translator.inbox\"}"
)

mq9_discover_agents

Find Agents with specific capabilities.

Parameters:

Parameter	Type	Required	Default	Description
`query`	string	No	—	Natural-language query or `tag:xxx` tag query
`limit`	integer	No	20	Maximum number of Agents to return

Example:

Find an Agent that can write Python code

LLM calls:

mq9_discover_agents(query="Agent that can write Python code")

Find by tag:

Find all Agents tagged 'translation'

LLM calls:

mq9_discover_agents(query="tag:translation")

mq9_unregister_agent

Deregister yourself and remove your entry from the registry. Call this when your Agent shuts down normally.

Parameters:

Parameter	Type	Required	Default	Description
`name`	string	Yes	—	Agent name used at registration

Example:

I'm going offline, deregister me

LLM calls:

mq9_unregister_agent(name="translation-agent-001")

Typical Scenarios

Scenario 1: Claude receives tasks sent by an external Agent

Conversation example:

User: Create an inbox called claude.worker.inbox and register me

Claude: [mq9_create_mailbox(name="claude.worker.inbox")]
        [mq9_register_agent(name="claude-worker-001", payload="...")]
        Inbox created and your identity registered.

User: Check my inbox

Claude: [mq9_fetch_messages(mail_address="claude.worker.inbox", group_name="claude-worker-001")]
        You have 3 new messages:
        1. From user-agent-001: Please help me translate...
        2. From task-coordinator: New task assignment...
        3. From monitor-agent: Status query...

Scenario 2: Claude coordinates multiple Agents to complete a task

Conversation example:

User: I have a Chinese text that needs to be translated into English and then summarized in 100 words.

Claude: Let me find the right Agents.
        [mq9_discover_agents(query="Chinese-English translation")]
        Found agent.translator.inbox

        [mq9_discover_agents(query="text summarization")]
        Found agent.summarizer.inbox

        I'll send it to the translation Agent first, then the summarization Agent.
        [mq9_send_message(mail_address="agent.translator.inbox", payload="...")]
        [mq9_fetch_messages(mail_address="claude.worker.inbox", group_name="claude-worker-001")]
        (waiting for translation result)
        [mq9_ack_message(mail_address="claude.worker.inbox", group_name="claude-worker-001", msg_id=3)]
        [mq9_send_message(mail_address="agent.summarizer.inbox", payload="<English translation>")]
        [mq9_fetch_messages(mail_address="claude.worker.inbox", group_name="claude-worker-001")]
        (waiting for summary result)

        Final result: ...

Scenario 3: Claude broadcasts session state to multiple Agents

User: Send the design proposal we just discussed to all architecture-related Agents

Claude: [mq9_discover_agents(query="tag:architecture")]
        Found 3 architecture-related Agents:
        - agent.architect.001
        - agent.architect.002
        - agent.reviewer.001

        [mq9_send_message(mail_address="agent.architect.001", payload="<proposal content>")]
        [mq9_send_message(mail_address="agent.architect.002", payload="<proposal content>")]
        [mq9_send_message(mail_address="agent.reviewer.001", payload="<proposal content>")]

        Sent to 3 Agents.

FAQ

Q1: `mailbox xxx does not exist` — what do I do?

The mailbox doesn't exist. Create it first:

Create mailbox <name>

Q2: Cannot connect to the broker

Check:

Is the broker running? (robust-ctl cluster status)
Is port 58080 accessible? (curl http://localhost:58080/health/node)
Is the URL in your AI tool's configuration correct?
Is port 58080 open in your firewall?

Q3: Claude doesn't call mq9 tools

Possible reasons:

The MCP configuration file hasn't taken effect (restart the AI tool)
The user's request didn't contain a clear communication intent, so the LLM didn't recognize it should use mq9

Try being explicit: "Use mq9 to help me..." to guide the LLM.

Q4: The message was sent but the recipient didn't receive it

Check:

Is the recipient mailbox name correct?
Did the message actually arrive? (use mq9_query_mailbox to inspect the mailbox)
Is the recipient's group_name correct? Has the offset skipped past the message?

Q5: `fetch_messages` returns no messages

Possible reasons:

There are genuinely no new messages in the mailbox
group_name is wrong (each group maintains its own offset independently)
The consumer offset has reached the end (use reset_to="earliest" to re-read from the beginning)

Q6: How do I delete a message?

mq9 MCP does not expose a delete tool by default to avoid accidental deletion. The recommended approach is to let messages expire via TTL, or delete them manually using the mq9 protocol CLI (robustmq-cli).

Q7: How do I deploy to production?

Deploy the broker on a remote server and change the AI tool's URL to the remote address (http://broker.example.com:58080/mcp)
If broker authentication is enabled, add a token in the AI tool's headers
Manage the broker process with systemd or Kubernetes

Yes. Use a different group_name in each AI tool's fetch/ack calls; the broker independently maintains each group's consumer offset. Multiple Agents connecting to the same broker simultaneously is the standard usage pattern for mq9.

Q9: Do I need a dedicated port for MCP?

No. The MCP endpoint is mounted at /mcp under the broker's existing port 58080 HTTP service, reusing the same HTTP server. No additional port is needed.

Q10: How do I disable MCP?

If you need to disable MCP for security reasons, disable the /mcp path in the port 58080 HTTP server configuration — refer to the RobustMQ configuration documentation for specifics. Disabling MCP does not affect any other broker capabilities.

Feedback and Support

GitHub Issues: https://github.com/robustmq/robustmq/issues
Documentation: https://docs.robustmq.org/mq9
Community: see the RobustMQ website

When filing an issue, please include:

RobustMQ version (curl http://localhost:58080/api/info)
AI tool and version (e.g. Claude Desktop 0.7.0)
Broker-side logs (mq9 protocol errors + MCP endpoint errors)
Steps to reproduce

mq9 MCP User Guide ​

Introduction ​

Prerequisites ​

Quick Start ​

1. Confirm the broker is running ​

2. Configure your AI tool ​

Claude Desktop ​

Cursor ​

Cline / Continue / other HTTP MCP tools ​

3. Verify the connection ​

stdio Mode ​

Tool List ​

Tool Reference ​

mq9_create_mailbox ​

mq9_send_message ​

mq9_fetch_messages ​

mq9_ack_message ​

mq9_query_mailbox ​

mq9_register_agent ​

mq9_discover_agents ​

mq9_unregister_agent ​

Typical Scenarios ​

Scenario 1: Claude receives tasks sent by an external Agent ​

Scenario 2: Claude coordinates multiple Agents to complete a task ​

Scenario 3: Claude broadcasts session state to multiple Agents ​

FAQ ​

Q1: mailbox xxx does not exist — what do I do? ​

Q2: Cannot connect to the broker ​

Q3: Claude doesn't call mq9 tools ​

Q4: The message was sent but the recipient didn't receive it ​

Q5: fetch_messages returns no messages ​

Q6: How do I delete a message? ​

Q7: How do I deploy to production? ​

Q8: Can multiple AI tools share a single broker? ​

Q9: Do I need a dedicated port for MCP? ​

Q10: How do I disable MCP? ​

Feedback and Support ​

mq9 MCP User Guide

Introduction

Prerequisites

Quick Start

1. Confirm the broker is running

2. Configure your AI tool

Claude Desktop

Cursor

Cline / Continue / other HTTP MCP tools

3. Verify the connection

stdio Mode

Tool List

Tool Reference

mq9_create_mailbox

mq9_send_message

mq9_fetch_messages

mq9_ack_message

mq9_query_mailbox

mq9_register_agent

mq9_discover_agents

mq9_unregister_agent

Typical Scenarios

Scenario 1: Claude receives tasks sent by an external Agent

Scenario 2: Claude coordinates multiple Agents to complete a task

Scenario 3: Claude broadcasts session state to multiple Agents

FAQ

Q1: `mailbox xxx does not exist` — what do I do?

Q2: Cannot connect to the broker

Q3: Claude doesn't call mq9 tools

Q4: The message was sent but the recipient didn't receive it

Q5: `fetch_messages` returns no messages

Q6: How do I delete a message?

Q7: How do I deploy to production?

Q8: Can multiple AI tools share a single broker?

Q9: Do I need a dedicated port for MCP?

Q10: How do I disable MCP?

Feedback and Support