Available Tools

When an LLM connects to the MCP server, it discovers a set of tools that map to EventSourcingDB operations. This page describes each tool from an application perspective, explaining what it does and when it is useful.

Health and Authentication

esdb_ping checks whether the connection to EventSourcingDB is healthy. The LLM can use this tool to verify that the MCP server can reach the database before attempting any other operation.

esdb_verify_api_token verifies that the configured API token is valid for the EventSourcingDB instance. This is useful for confirming that the MCP server is properly authenticated before performing operations that require authorization.

Writing Events

esdb_write_events stores one or more event candidates in EventSourcingDB. Each event candidate must include a source, subject, type, and data payload. Optional preconditions can be specified to ensure write consistency. The LLM uses this tool when you ask it to record new events, such as acquiring a book or registering a reader.

esdb_register_event_schema associates a JSON Schema with a specific event type. Once a schema is registered, EventSourcingDB validates incoming events of that type against the schema. This tool is useful when you want to enforce a particular structure for your events.

Reading Events

esdb_read_events retrieves events from EventSourcingDB for a given subject. It supports filtering by event ID bounds, ordering, recursive reading from sub-subjects, and limiting the number of results. The LLM uses this tool to show you the event history of a particular entity or to inspect individual events.

esdb_read_subjects lists all subjects under a given base subject. This helps the LLM discover what entities exist in the event store, for example all books or all readers in a library system.

esdb_read_event_types returns all event types that have been stored, along with any schemas that have been registered for them. The LLM uses this tool to understand the structure of the data before formulating queries or writing events.

esdb_read_event_type retrieves the JSON Schema for a specific event type. While esdb_read_event_types gives a broad overview, this tool is useful when the LLM needs the detailed schema for one particular event type.

Querying

esdb_run_eventql_query executes an EventQL query against the event store and returns the results. EventQL is the query language of EventSourcingDB and supports filtering, grouping, and projecting events. The LLM uses this tool when you ask analytical questions that span multiple subjects or require aggregation, such as counting how many books a reader has borrowed or finding the most active readers in a library system.

esdb_get_eventql_documentation returns the EventQL query language documentation, including syntax, examples, and reference material. The LLM uses this tool to learn about EventQL before writing queries, which leads to more accurate and idiomatic queries.

For practical examples that show how these tools work together in realistic scenarios, see Working with Events.