MCP Server

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs. The Apache Iggy MCP Server is an implementation of the MCP protocol for the message streaming infrastructure. It is built using the rmcp crate and supports both stdio and HTTP transports.

Getting started

Start an Iggy 0.9.0 or edge broker using the getting started guide. From the matching apache/iggy checkout, run:

IGGY_MCP_IGGY_USERNAME=iggy IGGY_MCP_IGGY_PASSWORD=iggy cargo run --bin iggy-mcp

These are the development credentials configured in that guide. Use your broker's credentials or a PAT when connecting to an existing installation.

The docker image is available, and can be fetched via docker pull apache/iggy-mcp:0.5.0.

Configuration

The minimal viable configuration requires at least the Iggy credentials, used to create the TCP connection to the running Iggy server that the MCP server talks to. You can choose between HTTP (the default) and STDIO transports (e.g. for the local usage with tools such as Claude Desktop choose stdio).

transport = "http" # http (default) or stdio are supported

[iggy]
address = "localhost:8090" # TCP address of the Iggy server
username = "iggy"
password = "iggy"
# token = "secret" # Personal Access Token (PAT) can be used instead of username and password
# token = "file:/run/secrets/iggy_pat" # PAT can also be read from a file
# consumer = "iggy-mcp" # Optional consumer name

[iggy.tls] # Optional TLS configuration for the Iggy TCP connection
enabled = false
ca_file = "path/to/ca.pem"
domain = "" # Optional domain for TLS connection

[http] # Optional HTTP API configuration
address = "127.0.0.1:8082"
path = "/mcp"

[http.cors] # Optional CORS configuration for HTTP API
enabled = false
allowed_methods = ["GET", "POST", "PUT", "DELETE"]
allowed_origins = ["*"]
allowed_headers = ["content-type"]
exposed_headers = [""]
allow_credentials = false
allow_private_network = false

[http.tls] # Optional TLS configuration for HTTP API
enabled = false
cert_file = "core/certs/iggy_cert.pem"
key_file = "core/certs/iggy_key.pem"

[permissions]
create = true
read = true
update = true
delete = true

[telemetry] # Optional OpenTelemetry integration
enabled = false
service_name = "iggy-mcp"

[telemetry.logs]
transport = "grpc" # grpc or http
endpoint = "http://localhost:4317"

[telemetry.traces]
transport = "grpc" # grpc or http
endpoint = "http://localhost:4317"

Set telemetry.enabled = true to export to a running collector. For HTTP export, set transport = "http" and use complete signal URLs: http://localhost:4318/v1/logs for logs and http://localhost:4318/v1/traces for traces. The MCP server does not append those paths.

The configuration file must be in the toml format. By default, the server looks for core/ai/mcp/config.toml relative to its working directory. Set IGGY_MCP_CONFIG_PATH to use another path. Embedded defaults are loaded first, then the file if it exists, then environment overrides.

Each setting can also be overridden using IGGY_MCP_<SECTION>_<KEY>, for example IGGY_MCP_IGGY_USERNAME or IGGY_MCP_HTTP_ADDRESS. Nested settings use the same underscore convention, such as IGGY_MCP_IGGY_TLS_ENABLED. Set IGGY_MCP_ENV_PATH to load a particular dotenv file; otherwise .env is searched for in the current directory and its parents. Existing environment variables take precedence over dotenv values.

The token value can be either a literal PAT or a file: reference such as token = "file:/run/secrets/iggy_pat", in which case the token is read from the given file and surrounding whitespace is removed (~/ is expanded to the home directory). A non-empty token takes precedence over the username and password.

Available tools

The MCP server exposes these 41 tools:

Server

Streams

Topics

Partitions & Segments

Messages

Consumer Groups

Consumer Offsets

Users & Access Tokens

Permissions

The [permissions] section provides a first layer of access control, checked before any request is forwarded to the Iggy server. This lets you restrict the MCP server to read-only operations, for example:

[permissions]
create = false
read = true
update = false
delete = false

poll_messages requires update as well as read when auto_commit is true or the next strategy is used. The next strategy enables auto-commit automatically. Storing an offset requires update; deleting an offset requires delete. PAT creation and deletion require create and delete, respectively.

On top of this, the Iggy user account used by the MCP server has its own granular permissions. For production use, create a dedicated user with the minimum required permissions.

Claude Desktop integration

Set command to the absolute path of the built iggy-mcp executable. This Claude Desktop example uses the broker and development credentials from the getting started guide:

{
  "mcpServers": {
    "iggy": {
      "command": "/path/to/iggy-mcp",
      "args": [],
      "env": {
        "IGGY_MCP_TRANSPORT": "stdio",
        "IGGY_MCP_IGGY_ADDRESS": "localhost:8090",
        "IGGY_MCP_IGGY_USERNAME": "iggy",
        "IGGY_MCP_IGGY_PASSWORD": "iggy"
      }
    }
  }
}

Docker

Create a shared network and start a development broker that advertises its container name:

docker network create iggy-mcp
docker run -d --name iggy-server --network iggy-mcp \
  --security-opt seccomp=unconfined --ulimit memlock=-1:-1 \
  -e IGGY_ROOT_USERNAME=iggy -e IGGY_ROOT_PASSWORD=iggy \
  -e IGGY_TCP_ADDRESS=0.0.0.0:8090 \
  -e IGGY_NODE_ADVERTISED_ADDRESS=iggy-server \
  apache/iggy:0.9.0

After the broker is ready, run the MCP server on the same network:

docker run --rm --network iggy-mcp -e IGGY_MCP_TRANSPORT=http \
  -e IGGY_MCP_HTTP_ADDRESS=0.0.0.0:8082 \
  -e IGGY_MCP_IGGY_ADDRESS=iggy-server:8090 \
  -e IGGY_MCP_IGGY_USERNAME=iggy \
  -e IGGY_MCP_IGGY_PASSWORD=iggy \
  -p 127.0.0.1:8082:8082 \
  apache/iggy-mcp:0.5.0

The HTTP endpoint uses the configured Iggy account for every MCP client. This example publishes it only on the host loopback interface.

The default HTTP address is 127.0.0.1:8082, which inside a container is unreachable from the outside, so IGGY_MCP_HTTP_ADDRESS=0.0.0.0:8082 is required for the published port to work.

Systemd integration

Build with the systemd cargo feature to enable systemd readiness and watchdog notifications:

cargo build --bin iggy-mcp --release --features iggy-mcp/systemd

Readiness is sent after the HTTP listener starts or the stdio MCP session initializes. When systemd enables the watchdog, the server sends keep-alive notifications at half the configured watchdog interval. SIGINT, SIGTERM, or stdio client disconnect stops the server and sends a stopping notification.