Monedula
monedula-sim-link docs menu

Use the MCP server

Register monedula-sim-link mcp with Claude Code or Claude Desktop so an AI agent can build Kafka Simulator links and visualize a live cluster read-only.

How-to guides 5 of 6

2 min read

Updated 16 October 2026

Markdown

On this page

monedula-sim-link mcp serves the Model Context Protocol over stdio, so any MCP client can generate playground links.

Before you start

  • monedula-sim-link installed, as described in the install section. The examples assume it is on your PATH; if it is not, give its absolute path as the command.
  • An MCP client: Claude Code, Claude Desktop or another one.

Steps

1. Register the server with your client

{
  "mcpServers": {
    "monedula-sim-link": {
      "command": "monedula-sim-link",
      "args": ["mcp"]
    }
  }
}
claude mcp add monedula-sim-link -- monedula-sim-link mcp
{
  "mcpServers": {
    "monedula-sim-link": {
      "command": "monedula-sim-link",
      "args": ["mcp", "--base-url", "https://monedula.dev/kafka-simulator/playground"]
    }
  }
}

For Claude Code, put the first file at the root of your project as .mcp.json, or run the command. For Claude Desktop, add the last block to claude_desktop_config.json. --base-url is optional, and the Desktop example shows it with its default; Point links at a local playground changes it.

The server has four tools (MCP tools reference), and the agent picks one from what you ask:

  • A scenario you name. “Open scenario 00.1.3 in the simulator” uses open_scenario and returns a link to the curated scenario, paused on its scripted walkthrough.
  • A cluster you describe. “Show me a six-broker cluster with an orders topic and a payments topic with 6 partitions, then kill broker 2 after a few seconds” uses build_playground_url. The agent turns the description into a cluster shape and a list of timed actions.
  • A link you want checked. “What would the playground load from this link?” uses validate_actions, which reports the entries the playground would silently drop.
  • A live cluster. “Visualize my cluster at broker1:9092, topics orders and payments” uses cluster_to_url. It connects read-only, with the same pipeline as connect.

3. Connect to a live cluster with care

cluster_to_url takes the same inputs as connect, except that the paths to caCert, clientCert and clientKey are files on the machine where the MCP server runs, not on the machine of the client, and that its producers input always uses the 15-minute window. Prefer the MONEDULA_SIM_LINK_PASSWORD environment variable on the server’s machine to a password that the agent passes in a request, because the request is part of the conversation.

Check it worked

Ask your agent to open scenario 00.1.3. The reply is the link:

https://monedula.dev/kafka-simulator/playground?scenario=00.1.3

If the agent does not offer the tools, check that the client started the server: the command must run as monedula-sim-link mcp, and standard output carries only the protocol stream, so a wrapper script that prints anything else breaks it. The server logs to standard error.