# 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](/docs/eventsourcingdb/mcp-server/getting-started)** and **[Connecting to an LLM](/docs/eventsourcingdb/mcp-server/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.