Connect your agent

How to connect any MCP client to Eventum, for local authoring or live management.

There are two ways to connect your agent to Eventum:

stdio — your MCP client runs Eventum locally. Best for building, previewing, and running generators on your own machine.
HTTP — your client connects to a running Eventum server, and can also manage the generators running there.

Start with stdio. Move to HTTP once you need to manage a live server.

Prerequisites

Eventum installed. See Installation.
A generators directory — the folder Eventum reads your generators from. Use an existing one, or create an empty folder for the agent to populate:

mkdir -p /path/to/generators

The commands below run Eventum with uv run. If Eventum is already on your PATH, omit the uv run prefix.

Local authoring over stdio

Over stdio your client launches Eventum itself. There is no server to run, and every MCP client supports it.

Add Eventum to your client

Add an eventum entry to your client's MCP configuration, using an absolute path to your generators directory:

mcp.json

{
  "mcpServers": {
    "eventum": {
      "command": "uv",
      "args": ["run", "eventum", "mcp", "--generators-dir", "/path/to/generators"]
    }
  }
}

Most clients — including Claude Desktop and Windsurf — accept this same mcpServers format. The file's location varies between clients, so check your client's documentation for the exact path.

claude mcp add eventum -- uv run eventum mcp --generators-dir /path/to/generators

By default the server is registered only for the project directory you run the command from. Add -s user to make it available in all your projects.

codex mcp add eventum -- uv run eventum mcp --generators-dir /path/to/generators

~/.cursor/mcp.json

{
  "mcpServers": {
    "eventum": {
      "command": "uv",
      "args": ["run", "eventum", "mcp", "--generators-dir", "/path/to/generators"]
    }
  }
}

Use .cursor/mcp.json inside a repository to register the server for that project only.

~/.gemini/settings.json

{
  "mcpServers": {
    "eventum": {
      "command": "uv",
      "args": ["run", "eventum", "mcp", "--generators-dir", "/path/to/generators"]
    }
  }
}

.vscode/mcp.json

{
  "servers": {
    "eventum": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "eventum", "mcp", "--generators-dir", "/path/to/generators"]
    }
  }
}

Reload your client

Restart your client, or reload its MCP configuration. Eventum should appear among its connected MCP servers, with its tools available to the agent.

Start building

Describe the data you want — for example:

build a generator that emits one JSON web access-log event per second, then preview ten events

The usage scenarios cover more of what you can ask for.

By default the agent can read and write files in your generators directory. Add --read-only to let it explore and preview without changing anything. See the eventum mcp reference for all options.

Over HTTP your client connects to a running Eventum server. The agent can do everything it does over stdio, and also manage the generators running on that server. Access is protected by the server's credentials.

Enable the MCP server in `eventum.yml`

eventum.yml

server.mcp.enabled: true
server.mcp.allow_write: true
server.mcp.path: "/mcp"

Managing live generators requires allow_write: true. Leave it false — the default — to limit the agent to exploring and previewing. See the configuration reference for every option.

Start the server

eventum run -c eventum.yml

With the defaults, the MCP endpoint is available at http://localhost:9474/mcp/.

Point your client at the server

Add the endpoint and the server's credentials to your client. The Authorization value is Basic followed by username:password in base64; the examples below encode the default eventum:eventum.

mcp.json

{
  "mcpServers": {
    "eventum": {
      "url": "http://localhost:9474/mcp/",
      "headers": {
        "Authorization": "Basic ZXZlbnR1bTpldmVudHVt"
      }
    }
  }
}

Most clients accept this same mcpServers format. The file's location varies between clients, so check your client's documentation for the exact path.

claude mcp add --transport http eventum http://localhost:9474/mcp/ --header "Authorization: Basic ZXZlbnR1bTpldmVudHVt"

By default the server is registered only for the project directory you run the command from. Add -s user to make it available in all your projects.

~/.codex/config.toml

[mcp_servers.eventum]
url = "http://localhost:9474/mcp/"
http_headers = { "Authorization" = "Basic ZXZlbnR1bTpldmVudHVt" }

~/.cursor/mcp.json

{
  "mcpServers": {
    "eventum": {
      "url": "http://localhost:9474/mcp/",
      "headers": {
        "Authorization": "Basic ZXZlbnR1bTpldmVudHVt"
      }
    }
  }
}

gemini mcp add --transport http --header "Authorization: Basic ZXZlbnR1bTpldmVudHVt" eventum http://localhost:9474/mcp/

.vscode/mcp.json

{
  "servers": {
    "eventum": {
      "type": "http",
      "url": "http://localhost:9474/mcp/",
      "headers": {
        "Authorization": "Basic ZXZlbnR1bTpldmVudHVt"
      }
    }
  }
}

Reload the client to enable the live-management tools alongside the authoring ones.

Change the default eventum:eventum credentials before exposing the server on a network, and leave allow_write off unless the agent needs to write files or control generators.

Tools & resources

Everything the agent can call and read.

Usage scenarios

Worked examples — build, operate, and diagnose generators.