Queen Message Queue

Using the @repo/mcp-queen server to interact with the Queen message queue at queen.trustzero.co — push, pop, peek, ack, and manage queues directly from an AI assistant.

The @repo/mcp-queen package is an MCP server that connects AI assistants to the Queen message queue — a C++ message queue service (libqueen v1.0.0) running at queen.trustzero.co.

Once connected, an AI assistant can inspect queue health, push and consume messages, manage queue lifecycle, and monitor throughput — all through natural language.

The server is already registered in .vscode/mcp.json. It will appear in your MCP servers list and prompt for a QUEEN_API_KEY on first use (leave blank if the server does not require authentication).

Claude Desktop

Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "queen": {
      "command": "bun",
      "args": ["run", "/path/to/netra/packages/mcp-queen/src/index.ts"],
      "env": {
        "QUEEN_URL": "https://queen.trustzero.co",
        "QUEEN_API_KEY": ""
      }
    }
  }
}

Restart Claude Desktop — the queen_* tools will be available in your conversations.

Environment Variables

Variable	Default	Description
`QUEEN_URL`	`https://queen.trustzero.co`	Base URL of the Queen server
`QUEEN_API_KEY`	(empty)	Bearer token for authenticated endpoints

Tools

Health & Metrics

`queen_health`

Returns the full health status of the Queen server.

Check the health of the Queen server

Response includes: server version, database connection status, worker ID, queue config cache hit rate, and shared state configuration.

`queen_metrics`

Returns runtime performance metrics.

Show me the Queen server metrics

Response includes: CPU usage, memory (heap, RSS), database pool size and idle connections, message throughput rate, request rate, and uptime.

Queue Management

`queen_list_queues`

Lists all queues configured on the server. The current deployment has 6 queues.

List all queues on Queen

`queen_get_queue`

Returns configuration and statistics for a specific queue.

Get the status of the "events" queue

Parameter	Type	Required	Description
`queue`	string	✓	Queue name

`queen_create_queue`

Creates a new queue with optional configuration.

Create a queue called "alerts" with a 30-second visibility timeout and max 3 retries

Parameter	Type	Required	Description
`queue`	string	✓	Queue name
`visibility_timeout`	number	—	Seconds a popped message stays invisible (default: server config)
`max_retries`	number	—	Max delivery attempts before dead-lettering
`delay`	number	—	Default push delay in seconds
`dead_letter_queue`	string	—	Queue name for failed messages

`queen_delete_queue`

Permanently deletes a queue and all its messages.

Delete the "temp-jobs" queue

`queen_purge_queue`

Clears all messages from a queue without deleting it.

Purge all messages from the "dead-letters" queue

Message Operations

`queen_push`

Pushes one or more messages onto a queue.

Push a message onto the "network-events" queue with body { "device": "cam-01", "type": "anomaly" }

Parameter	Type	Required	Description
`queue`	string	✓	Queue name
`messages`	array	✓	Array of message objects
`messages[].body`	any	✓	Message payload — any JSON value
`messages[].delay`	number	—	Per-message delay in seconds
`messages[].priority`	number	—	Higher = delivered first

`queen_pop`

Pops and locks messages from a queue. Locked messages are invisible to other consumers until acknowledged or the visibility timeout expires.

Pop the next 5 messages from the "policy-actions" queue

Parameter	Type	Required	Description
`queue`	string	✓	Queue name
`count`	number	—	Messages to pop (default: 1, max: 100)
`visibility_timeout`	number	—	Lock duration in seconds

`queen_peek`

Inspects messages without locking or consuming them.

Show me the first 10 messages in the "alerts" queue

Parameter	Type	Required	Description
`queue`	string	✓	Queue name
`count`	number	—	Messages to return (default: 10)

`queen_ack`

Acknowledges a message, permanently removing it after successful processing.

Acknowledge message msg_01HWXK9M from the "policy-actions" queue

Parameter	Type	Required	Description
`queue`	string	✓	Queue name
`message_id`	string	✓	Message ID from `queen_pop`

`queen_nack`

Negatively acknowledges a message, making it visible again for retry.

Nack message msg_01HWXK9M with a 60-second delay

Parameter	Type	Required	Description
`queue`	string	✓	Queue name
`message_id`	string	✓	Message ID from `queen_pop`
`delay`	number	—	Seconds before redelivery (default: 0)

`queen_delete_message`

Deletes a specific message by ID regardless of its lock state.

Delete message msg_01HWXK9M from the "alerts" queue

Example Workflows

Monitor queue health

Check Queen's health, then show me the metrics and list all queues with their sizes.

Process a batch of messages

Pop 10 messages from the "network-events" queue, summarize their contents,
then ack each one.

Debug a stuck queue

Peek at the first 20 messages in the "dead-letters" queue and tell me
why they might have failed.

Push a policy action

Push a message onto the "policy-actions" queue with body:
{ "action": "isolate", "device_id": "dev_camera_floor3_east", "reason": "anomaly detected" }

Source

The server source is at packages/mcp-queen/ in this monorepo:

packages/mcp-queen/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── client.ts         # HTTP client for queen.trustzero.co
│   └── tools/
│       ├── health.ts     # queen_health, queen_metrics
│       ├── queues.ts     # queue CRUD + purge
│       └── messages.ts   # push, pop, peek, ack, nack, delete
├── package.json
└── tsconfig.json

To run it directly:

cd packages/mcp-queen
bun run start

Setup

VS Code / Cursor