# Solace Broker Mcp

> Production MCP server for the Solace broker

- **Type:** MCP server
- **Install:** `agentstack add mcp-solaceproducts-solace-broker-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SolaceProducts](https://agentstack.voostack.com/s/solaceproducts)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [SolaceProducts](https://github.com/SolaceProducts)
- **Source:** https://github.com/SolaceProducts/solace-broker-mcp

## Install

```sh
agentstack add mcp-solaceproducts-solace-broker-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# solace-broker-mcp

[](https://github.com/SolaceProducts/solace-broker-mcp/actions)
[](LICENSE)
[](go.mod)
[](.github/CODE_OF_CONDUCT.md)

An MCP (Model Context Protocol) server for Solace event brokers, built with Go using the official [MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk).

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Architecture](#architecture)
- [Tools](#tools)
- [Guides](#guides)
- [Prerequisites](#prerequisites)
- [Quickstart](#quickstart)
  - [Configuration](#configuration)
  - [Binary Deployment](#binary-deployment)
  - [Install with go install](#install-with-go-install)
  - [Docker Deployment](#docker-deployment)
  - [Connect from Claude Code](#connect-from-claude-code)
  - [Connect from Solace Agent Mesh](#connect-from-solace-agent-mesh)
- [Development Setup](#development-setup)
  - [Configuration Options](#configuration-options)
- [Project Structure](#project-structure)
- [CI](#ci)
- [Contributing](#contributing)
- [Support](#support)
- [Security](#security)
- [Disclaimer](#disclaimer)
- [License](#license)

## Overview

An HTTP service that exposes Solace event broker management and monitoring to AI assistants through the Model Context Protocol (MCP). The server provides 40 tools: 24 read-only tools that query event broker status, inspect queues, diagnose client issues, and monitor message traffic, plus 16 optional write and action tools (off by default) for operational actions and configuration. It uses the Solace Element Management Protocol (SEMP) v1 and v2 APIs.

MCP-compatible clients, for example, Claude Code, invoke these tools using natural language. The AI assistant translates requests into tool calls. The server handles authentication, rate limiting, retries, and response formatting.

## Features

- **24 read-only monitoring tools** — Event broker status, Message VPNs, queues, clients, REST delivery points, bridges, Kafka receivers/senders, and SEMPv2 schema introspection
- **16 optional write and action tools** — Disconnect clients, delete queued messages, reset statistics, and create, update, or delete Message VPNs, queues, topic endpoints, and REST delivery points; gated behind `enable_write_tools` (off by default)
- **Client authentication** — Development mode (no auth), static bearer tokens, or OAuth 2.1/OIDC with JWT validation
- **Claim-based tool authorization** — Under OAuth mode, gate individual MCP tools by a configurable OIDC claim carrying the caller's group or role memberships (`groups` by default); `list-brokers` stays exempt so callers can always discover configured brokers
- **Multi-broker configuration** — Connect to multiple brokers and address them by configured alias
- **Retry and rate limiting** — Configurable backoff intervals and concurrent request limits per broker
- **Deployment options** — Standalone binary, Docker container, or Go source
- **TLS/HTTPS support** — Optional certificate-based transport encryption
- **Structured logging** — JSON output with automatic credential redaction

## Architecture

The server implements the MCP HTTP transport specification and exposes event broker operations as MCP tools. When an AI assistant invokes a tool, the server executes the corresponding SEMP API request against the target event broker and returns structured data to the client.

**Component diagram:**

```
                                           ┌───────────────────┐
                                           │  OAuth IdP        │
                                           │  (Keycloak etc.)  │ ◀── JWT validation
                                           │                   │     (production only)
                                           └─────────┬─────────┘
                                                     │
                                                     ▼
┌──────────────────┐   MCP over HTTP    ┌──────────────────────────┐   SEMPv1 + SEMPv2    ┌──────────────────┐
│                  │                    │   Broker MCP Server      │                      │                  │
│   AI Agent       │ ────────────────▶ │                          │  ──────────────────▶ │  Solace          │
│  (Claude Code,   │   JSON-RPC         │  • Auth (OAuth / token)  │   HTTP(S) /SEMP      │  Event           │
│  Claude Desktop) │   + Bearer JWT     │  • 24 read + 16 write    │                      │  Broker(s)       │
│                  │                    │  • Rate-limit + retry    │                      │                  │
│                  │ ◀──────────────── │  • SEMP client pool      │ ◀──────────────────  │                  │
└──────────────────┘                    └──────────────────────────┘  basic/bearer/oauth  └──────────────────┘
```

## Tools

The server exposes read-only tools grouped by what they inspect, plus write tools for operational actions and configuration management. Every tool except `list-brokers` and `describe-semp-schema` takes a `broker` parameter naming a configured broker alias. See the [Tools Reference](docs/tools-reference.md) for full per-tool parameters, output shape, and example invocations; the [user guide](docs/user-guide.md#tools-reference) has the narrative overview.

> **Note:** Results are interpreted and acted on by an AI assistant. Treat tool output as input to a human decision, not as verified fact, and confirm any write or destructive action before allowing it. See the [Disclaimer](#disclaimer).

| Category | Tools | Description |
|---|---|---|
| Discovery | `list-brokers`, `describe-semp-schema` | List configured broker aliases for use as the `broker` parameter; look up a SEMPv2 operation's request-body schema before calling a write tool |
| Broker status | `get-broker-status`, `get-redundancy-status` | Snapshot of version, uptime, resources, spool, and HA and mate-link state |
| Replication | `get-replication-status` | Replication role, sync eligibility, bridge status, transaction mode, and queued-message counts |
| Message VPN | `list-vpns`, `get-vpn-status`, `get-message-rates` | List VPNs, check per-VPN service status, read message and byte rates |
| Queues | `list-queues`, `get-queue-metrics` | List queues with cumulative spooled count and throughput; drill into a single queue for authoritative current depth, spool, and rates |
| Clients | `list-clients`, `get-client-details`, `list-client-subscriptions`, `list-slow-subscribers` | List connections, inspect per-client rates and discards, list subscriptions, filter for slow-subscriber-flagged clients |
| REST Delivery Points | `list-rdps`, `get-rdp-status` | List RDPs; inspect bindings, REST consumers, and last failure reason |
| Bridges | `list-bridges`, `get-bridge-status` | List bridges with inbound/outbound connection state; inspect a single bridge's connection establisher and failure category |
| Kafka | `list-kafka-receivers`, `get-kafka-receiver-status`, `list-kafka-senders`, `get-kafka-sender-status` | List Kafka Receivers/Senders with up/down status; inspect a single receiver's or sender's topic/queue-binding status |
| Discards | `get-discard-stats`, `list-queue-discards` | Broker-wide and per-VPN discard aggregates; per-queue discard counters |
| Actions | `delete-queue-messages`, `clear-queue-stats`, `disconnect-client`, `clear-client-stats` | One tool per operational action. Destructive tools (`delete-queue-messages`, `disconnect-client`) are annotated `destructiveHint` so clients can prompt before invocation, and their descriptions ask the model to confirm; the `clear-*-stats` tools are non-destructive. |
| Management | `create-message-vpn`, `update-message-vpn`, `delete-message-vpn`, `create-queue`, `update-queue`, `delete-queue`, `create-topic-endpoint`, `update-topic-endpoint`, `delete-topic-endpoint`, `create-rdp`, `update-rdp`, `delete-rdp` | Create, update, and delete Config-API objects (Message VPNs, queues, topic endpoints, REST delivery points). `delete-*` and the service-affecting `update-*` tools are annotated `destructiveHint` so clients can prompt before invocation, and their descriptions ask the model to confirm; `create-*` is additive and not annotated. |

**The action and management tools are write tools, gated behind `enable_write_tools: true` in the config — default off; not registered in `tools/list` when disabled.** That's 16 write tools in total (four action, 12 management), on top of the 24 read-only tools.

> **Confirmation is not enforced.** `enable_write_tools` is the only enforced control. `destructiveHint` and the confirmation text in tool descriptions are hints, not enforced by the MCP protocol — whether the user is actually prompted depends on the client and the model.

## Guides

- [User Guide](docs/user-guide.md) — overview, tools reference, deployment, and troubleshooting
- [Tools Reference](docs/tools-reference.md) — per-tool parameters, output schema, and example invocations for all 40 tools
- [Examples](docs/examples.md) — Claude Desktop config, natural-language queries, and multi-broker setup
- [Configuration](docs/configuration.md) — server settings, event broker config, client auth, and rate-limit/retry settings
- [Authentication](docs/authentication.md) — OAuth/OIDC and static token setup for MCP clients
- [Agent Mesh Integration](docs/sam-integration.md) — wire this MCP server into an Agent Mesh project as an agent

## Prerequisites

- Access to one or more Solace event brokers with SEMP management enabled
- [Docker](https://docs.docker.com/get-docker/) (for Docker deployment) or a supported OS/arch for the binary (linux/amd64, linux/arm64, darwin/amd64, darwin/arm64)
- **For Development / Building from Source:**
  - [Go 1.25+](https://go.dev/dl/) — required to build and run the MCP server from source
  - Not needed if using pre-built binaries or Docker images

## Quickstart

### Configuration

All deployment methods use the same YAML config file and `.env` credentials file.

**1. Create a config file** (`broker-config.yaml`):

```yaml
mcp_client_auth:
  mode: disabled        # no client auth — local development only

brokers:
  my-broker:
    url: "http://my-broker.example.com:8080"
    auth:
      mode: basic
      username: "${BROKER_USERNAME}"
      password: "${BROKER_PASSWORD}"
```

`mcp_client_auth.mode: disabled` skips client authentication entirely — only use this for local development. For production, set `mcp_client_auth.mode: oauth` and provide `issuer`, `audience`, and `resource_url`. A third mode, `static`, accepts a fixed bearer token for local development with realistic auth flow. See [Authentication](docs/authentication.md) for full setup instructions.

**Audit-log identity.** In `oauth` and `static` modes, every tool-invocation log line carries the caller's `sub`, `iss`, `client_id`, and `jti` claims (the latter three appear as `` when the IdP does not issue them). A separate sentinel `` is reserved for an internal coding error — it should never appear in production, and its presence indicates a bug in the server's claim-extraction code, not in the caller's token; alert on it. The request still completes and the audit line is still written. In `disabled` mode no client auth runs, so log lines carry no identity fields at all. **`disabled` and `static` modes are not real audit trails**: `disabled` lines have no attribution, and `static` lines attribute every invocation to the hardcoded `dev-user`. Use `oauth` mode for any deployment whose audit logs need to answer "who ran what tool against which broker?"

Under `oauth` mode with a `tool_authorization` policy configured, each gated tool call also emits a `"tool authorization"` audit line at the same `correlation_id` — logged at `INFO` on allow and `WARN` on deny, with a `decision_reason` code operators can filter and alert on. See [Tool authorization](docs/configuration.md#tool-authorization) for the full schema.

The same policy can also narrow `tools/list` to the tools each caller may invoke, so an agent is not handed tools it will be denied. Off by default; opt in with `filter_tools_list: true` and see [Filtering `tools/list`](docs/configuration.md#filtering-toolslist). This is discovery hygiene rather than access control — `tools/call` remains the enforcement point either way.

Each event broker needs:
- `url` — the SEMP management API base URL
- `auth.mode` — `basic`, `bearer`, or `oauth` (examples below use basic auth; for bearer token authentication, set `auth.mode: bearer` and provide `auth.token` instead; for OAuth token exchange, see [Step 2b: Configure broker OAuth (Hop 2)](docs/authentication.md#step-2b-configure-broker-oauth-hop-2))
- `auth.username` / `auth.password` — credentials (use `${VAR_NAME}` to reference environment variables)

**Broker alias contract.** The map key under `brokers:` (for example, `my-broker`) is the alias that appears in tool inputs (`broker="my-broker"`), logs, and `list-brokers` output. Aliases must be 1–63 characters, contain only letters, digits, and hyphens, and start and end with an alphanumeric character. Comparison is case-insensitive — `Prod` and `prod` collide and the server refuses to start. Original casing is preserved in all user-facing output.

**2. Create a `.env` file** next to the config file:

```env
BROKER_USERNAME=admin
BROKER_PASSWORD=admin
```

The `.env` file is loaded automatically. Environment variables set directly (for example, in CI/CD) take precedence over `.env` values. See [Configuration Options](#configuration-options) for all settings, including port, TLS, and file path overrides.

---

Select a deployment method:
- **[Binary](#binary-deployment)** - Single executable with no dependencies; suitable for local development and VM deployment
- **[go install](#install-with-go-install)** - Build and install from source with the Go toolchain; suitable when you already have Go and want the latest tagged release on your `PATH`
- **[Docker](#docker-deployment)** - Containerized deployment; suitable for production and Kubernetes environments

For contributors running from source, see [Development Setup](#development-setup).

### Binary Deployment

Download the archive for your platform from the [latest release](https://github.com/SolaceProducts/solace-broker-mcp/releases/latest). Available platforms: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64.

Download the checksums file, verify the checksum, and extract:

```bash
# Verify checksum
shasum -a 256 -c checksums-sha256.txt --ignore-missing

# Extract
tar xzf solace-broker-mcp-v*.tar.gz
```

Every release archive also carries a build provenance attestation. Verifying it proves the archive was produced by this repository's `release.yml` workflow, not rebuilt or replaced by someone else — a stronger guarantee than the checksum, which only proves the file matches the checksums list published beside it. Requires the [GitHub CLI](https://cli.github.com/), authenticated with `gh auth login` (the attestation is fetched from the GitHub API, which needs a token even for a public repository):

```bash
gh attestation verify solace-broker-mcp-v1.2.0-linux-amd64.tar.gz \
  --repo SolaceProducts/solace-broker-mcp \
  --signer-workflow SolaceProducts/solace-broker-mcp/.github/workflows/release.yml
```

Pass the exact archive filename — the command takes a single file, so a glob such as `solace-broker-mcp-v*.tar.gz` fails once you have more than one archive in the directory. `--signer-workflow` is what pins the attestation to the release workflow; `--repo` alone would accept an attestation minted by any workflow in this repository.

The archive contains the binary, an example config (`broker-config.example.yaml`), and the license. Copy the example config to `broker-config.yaml` and modify as needed.

Run the MCP server with the config file:

```bash
CONFIG_FILE=./broker-config.yaml ./solace-broker-mcp
```

If the config file is named `broker-config.yaml` in the current directory, the server does not require `CONFIG_FILE`.

Verify:

```bash
curl http://localhost:9090/livez
# {"stat

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SolaceProducts](https://github.com/SolaceProducts)
- **Source:** [SolaceProducts/solace-broker-mcp](https://github.com/SolaceProducts/solace-broker-mcp)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-solaceproducts-solace-broker-mcp
- Seller: https://agentstack.voostack.com/s/solaceproducts
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.