Working with Events

This guide walks you through practical scenarios that show how to interact with EventSourcingDB through the MCP server. Each scenario uses the library domain previously mentioned in the documentation and demonstrates a prompt you can give to your LLM along with a description of what happens behind the scenes.

Before You Begin

These scenarios assume that you have a running MCP server connected to an EventSourcingDB instance, and that your LLM is configured to use it. If not, see Getting Started and Connecting to an LLM.

Exploring the Event Store

A good starting point is to find out what data already exists. You can ask your LLM:

List all subjects under /books and tell me what event types exist in the store.

The LLM will call esdb_read_subjects with the base subject /books to discover all book entities, and then call esdb_read_event_types to retrieve the list of known event types. It combines both results into a summary that tells you which books are in the store and what kinds of events have been recorded.

Writing Events

To record new events, describe what happened in natural language:

The library acquired a new book: "Rendezvous with Rama" by Arthur C. Clarke, ISBN 978-0358380221. Assign it to subject /books/84.

The LLM will call esdb_write_events with an event candidate of type io.eventsourcingdb.library.book-acquired, setting the subject to /books/84 and including the title, author, and ISBN in the data payload.

You can also record multiple events at once:

Register a new reader "Alice" under /readers/7 and immediately borrow book /books/84 to her.

The LLM will construct two event candidates and call esdb_write_events to store them both.

Reading Events and Running Queries

To inspect the history of a specific entity, ask your LLM:

Show me the full event history for /books/42.

The LLM will call esdb_read_events filtered by the subject /books/42 and present the events in chronological order, including their types, timestamps, and data payloads.

For more analytical questions, the LLM uses EventQL:

How many books were acquired in the last 30 days?

The LLM will call esdb_run_eventql_query with a query that filters events of type io.eventsourcingdb.library.book-acquired by their timestamp and counts the results.

Registering Schemas

To enforce a structure for your events, you can ask the LLM to register a schema:

Register a JSON Schema for the event type io.eventsourcingdb.library.book-acquired. The data must contain title (string), author (string), and isbn (string), all required.

The LLM will call esdb_register_event_schema with a JSON Schema that defines the expected structure. From that point on, EventSourcingDB will validate all incoming events of that type against the schema.

Finding Answers in Complex Data

The MCP server is especially valuable when you need to combine multiple operations to answer a question:

Which books are currently borrowed and haven't been returned yet?

To answer this, the LLM will call esdb_run_eventql_query with an EventQL query that identifies books with a book-borrowed event that is not followed by a book-returned event. The result is a list of books that are still out on loan, without you having to write the query yourself.

This kind of interactive, exploratory querying is where the MCP server provides the most value. Instead of crafting EventQL queries manually, you describe what you want to know, and the LLM translates your intent into the appropriate tool calls.