---
title: "Use the MCP server"
description: "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."
url: https://monedula.dev/flock/docs/sim-link/how-to/use-the-mcp-server/
---
`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](/flock/docs/sim-link/#install). 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

<Tabs group="sim-link-mcp-client" labels={['Claude Code: .mcp.json', 'Claude Code: command', 'Claude Desktop']} label="MCP client">

```json
{
  "mcpServers": {
    "monedula-sim-link": {
      "command": "monedula-sim-link",
      "args": ["mcp"]
    }
  }
}
```

```bash
claude mcp add monedula-sim-link -- monedula-sim-link mcp
```

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

</Tabs>

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](/flock/docs/sim-link/how-to/point-at-a-local-playground/) changes it.

### 2. Ask for a link

The server has four tools ([MCP tools reference](/flock/docs/sim-link/reference/mcp-tools/)), 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:

```text
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.

## Related

- [The read-only guarantee](/flock/docs/sim-link/concepts/read-only-guarantee/) applies to `cluster_to_url` as well.
- The [`mcp` command reference](/flock/docs/sim-link/reference/cli/mcp/) lists its flag and exit codes.