Overview

The Diffusion MCP Server is a lightweight management service for Diffusion deployments that exposes common administrative operations over HTTP. It centralizes tasks such as connecting to Diffusion brokers, discovering and creating topics, controlling client sessions, configuring topic views, and exporting operational metrics for monitoring. The server acts as an MCP (Model Context Protocol) façade so external tooling and automation can manage Diffusion programmatically without embedding Diffusion client libraries.

This tool is useful for developers and operations engineers who want to automate or script Diffusion management tasks, integrate Diffusion into CI/CD or monitoring stacks, or provide a simple HTTP API for operational consoles. By combining topic and session management with Prometheus-compatible metrics, the server fits into observability workflows and simplifies operational automation.

Features

Connects to one or more Diffusion brokers and exposes management APIs
Browse existing topics and their types, schemas, and configuration
Create, update, and delete topics programmatically
Inspect and manage active client sessions, including termination
Configure topic views and derived views for aggregation or transformation
Expose runtime and Diffusion metrics in Prometheus format
Health and readiness endpoints for orchestration systems
Docker-friendly packaging and straightforward environment-based configuration

Installation / Configuration

Clone and build (Maven example):

git clone https://github.com/diffusiondata/diffusion-mcp-server.git
cd diffusion-mcp-server
mvn clean package
java -jar target/diffusion-mcp-server-<version>.jar

Run with Docker:

docker build -t diffusion-mcp-server .
docker run -d \
  -e DIFFUSION_HOST=diffusion.example.com \
  -e DIFFUSION_PORT=443 \
  -e DIFFUSION_USER=admin \
  -e DIFFUSION_PASS=secret \
  -e SERVER_PORT=8080 \
  -p 8080:8080 \
  diffusion-mcp-server

Environment variables (common):

DIFFUSION_HOST — Diffusion broker hostname or IP
DIFFUSION_PORT — Diffusion port (typically 80, 443 or custom)
DIFFUSION_USER / DIFFUSION_PASS — credentials for management connection
SERVER_PORT — HTTP port for this server
LOG_LEVEL — logging verbosity

Alternatively, set values in an application.properties / application.yml if the project uses Spring Boot:

diffusion.host=diffusion.example.com
diffusion.port=443
diffusion.user=admin
diffusion.password=secret
server.port=8080

Available Resources

Common API endpoints (typical paths — actual routes may vary by release):

Resource	Method	Description
/api/topics	GET	List topics and metadata
/api/topics	POST	Create a new topic (JSON payload describing type/config)
/api/topics/{topic}	GET	Get topic details
/api/topics/{topic}	DELETE	Delete a topic
/api/views	POST	Create or update a topic view
/api/sessions	GET	List active client sessions
/api/sessions/{id}	DELETE	Terminate a session
/metrics	GET	Prometheus-compatible metrics
/health or /actuator/health	GET	Health check for orchestrators

Prometheus scrape example:

scrape_configs:
  - job_name: diffusion-mcp
    static_configs:
      - targets: ['diffusion-mcp.example.com:8080']
    metrics_path: /metrics

Use Cases

Discover topics for an integration pipeline
- List topics to generate a mapping for downstream ETL:
```
curl -sS http://localhost:8080/api/topics | jq .
```

Create a new topic from CI/CD when deploying a new service

Example JSON to create a topic (type and config depend on your Diffusion deployment):

curl -X POST http://localhost:8080/api/topics \
  -H "Content-Type: application/json" \
  -d '{
    "topicPath": "services/orders",
    "type": "json",
    "description": "Order events topic",
    "properties": { "retention": "7d" }
  }'

Terminate a misbehaving client session without SSHing into brokers

# List sessions
curl http://localhost:8080/api/sessions | jq .
# Terminate a session by id
curl -X DELETE http://localhost:8080/api/sessions/<session-id>

Configure a server-side view to aggregate or filter topic data
- Post a view configuration to /api/views to create derived topics or aggregations used by applications.
Monitor Diffusion performance with Prometheus
- Add the /metrics endpoint to your scrape targets; build alerts on connection counts, message rates, or error counters exposed by the MCP server.

Tips and Best Practices

Secure the management endpoint behind a network ACL or authentication proxy; the server has powerful administrative operations.
Use orchestration health checks to ensure Diffusion connectivity before promoting a server instance to production.
Combine the metrics endpoint with dashboards (Grafana) to visualize topic throughput, session trends, and server health.
When automating topic creation, validate topic schemas in tests to prevent runtime incompatibilities.

Diffusion MCP Server: Topics, Sessions, Metrics