Diffusion

You can run a Diffusion MCP Server that connects to a Diffusion server to explore topics, manage topics, views, sessions, and various server metrics. It provides a development and monitoring aid, letting you inspect and configure a Diffusion environment from an MCP interface via either a local STDIO transport or an HTTP transport for multi-client access.

How to use

You use an MCP client to connect to the Diffusion MCP Server and perform actions such as exploring the topic tree, creating or updating topics, managing topic views, and retrieving server metrics. Start the MCP Server locally through STDIO if you want a single-user setup, or run it with HTTP transport for multi-client access. Once connected, issue commands through your MCP client to inspect structures, create topics, or fetch details about sessions, security stores, and configurations. For best learning, begin with exploring the topic tree, then try creating a simple topic and obtaining its details.

How to install

# Prerequisites
- Java 17 or later
- A path to a directory where you want to run the server

# Start the MCP Server (STDIO transport, single user)
java \
  -Xmx512m \
  -Dfile.encoding=UTF-8 \
  -jar diffusion-mcp-server-1.0.0.jar

# Optional: start the MCP Server with HTTP transport (multi-client)
java \
  -Dmcp.transport=https \
  -Djavax.net.ssl.keyStore=keystore.jks \
  -Djavax.net.ssl.keyStorePassword=changeit \
  -jar diffusion-mcp-server-1.0.0.jar

These commands start the MCP Server using the provided JAR. For STDIO, you can connect a client locally. For HTTP, you can connect multiple clients over TLS once configured with a keystore and appropriate host/port settings.

## Additional sections

Configuration and usage notes from the available setup options are:
- For STDIO transport, a typical inline client configuration starts the JVM with the MCP server JAR and may specify memory and encoding settings. The basic form is:
- Command: java
- Arguments: ["-Xmx512m", "-Dfile.encoding=UTF-8", "-jar", "diffusion-mcp-server-1.0.0.jar"]
- When using HTTP transport, you enable TLS and run the server with a keystore. A minimal example shows:
-Dmcp.transport=https \
-Djavax.net.ssl.keyStore=keystore.jks \
-Djavax.net.ssl.keyStorePassword=changeit \
-jar diffusion-mcp-server-1.0.0.jar
This makes the server listen on port 7443 by default.
If you plan to connect clients locally via HTTP, you can create a keystore first, then start the server with the HTTP transport options as shown above.

## Security and operational notes

Choose the appropriate security posture for your environment. The MCP server does not implement all Diffusion features and can create or remove topics and components if permissions allow. Avoid running on a production server with broad permissions unless you apply strict access controls. Always keep backups of persistence files and validate changes in a safe environment before applying them to production.

## Troubleshooting tips

- Verify Java 17+ is on your PATH and JAVA\_HOME points to a JDK 17+ installation.
- If you see zombie processes after stopping a client, terminate lingering processes related to the MCP server and clients.
- Check that the keystore is correctly configured when using HTTP transport, and ensure that the server TLS configuration allows the expected host/port.

## Available tools

### Explore topic tree

Browse the Topic Tree to view topics, their structure, and values available on the connected Diffusion server.

### Topic management

Create, update, and remove topics to shape the data model and topic hierarchy.

### Topic views

Create, list, and delete topic view specifications to customize how topic data is presented.

### Session management

Retrieve session details and map session properties to understand current usage and access.

### Metrics and alerts

Fetch server metrics and manage metric collectors and alerts for monitoring (Diffusion 6.12+ features).

### Security and authentication stores

Retrieve and update system security and authentication stores to control access.