Getting Started¶

This guide explains how to install and run the MCP server for EventSourcingDB. At the end, you will have a running MCP server that is connected to your EventSourcingDB instance and ready to accept connections from an LLM.

Before You Begin

You need a running EventSourcingDB instance and a valid API token for it. If you haven't set one up yet, see Running EventSourcingDB.

Installing the MCP Server¶

The MCP server is distributed as a Docker image. To pull the latest version, run:

docker pull thenativeweb/eventsourcingdb-mcp

Checking the Version¶

To verify the installation and display the current version along with the Git commit hash, use the version command:

docker run --rm thenativeweb/eventsourcingdb-mcp version

Running the MCP Server¶

To start the MCP server, use the run command. You need to tell the MCP server where to find your EventSourcingDB instance and how to authenticate:

docker run -it -p 3000:3000 \
  thenativeweb/eventsourcingdb-mcp run \
  --esdb-url <ESDB_URL> \
  --esdb-api-token <ESDB_API_TOKEN> \
  --http-enabled \
  --https-enabled=false

This starts the MCP server on port 3000 of your host machine. It connects to the EventSourcingDB instance at the given URL and authenticates using the provided API token.

Do Not Use These Configuration Settings In Production

Enabling HTTP and disabling HTTPS simplifies setup for development and testing but is not secure for production. In production, configure the MCP server with HTTPS by providing a certificate and private key through the --https-certificate-file and --https-private-key-file flags.

Configuration Options¶

The following table lists all available configuration options for the run command:

Flag	Description
`--esdb-url`	The URL of the EventSourcingDB instance to connect to.
`--esdb-api-token`	The API token used to authenticate with EventSourcingDB.
`--api-token`	An optional token that clients must provide to access the MCP server itself.
`--http-enabled`	Enables the HTTP endpoint. Defaults to `false`.
`--http-port`	The port for the HTTP endpoint. Defaults to `3000`.
`--https-enabled`	Enables the HTTPS endpoint. Defaults to `true`.
`--https-port`	The port for the HTTPS endpoint. Defaults to `4000`.
`--https-certificate-file`	Path to the TLS certificate file for HTTPS.
`--https-private-key-file`	Path to the TLS private key file for HTTPS.

Securing the MCP Server¶

By default, the MCP server does not require authentication from its clients. In any environment beyond local development, you should set the --api-token flag to require a Bearer token for all incoming connections:

docker run -it -p 3000:3000 \
  thenativeweb/eventsourcingdb-mcp run \
  --esdb-url <ESDB_URL> \
  --esdb-api-token <ESDB_API_TOKEN> \
  --api-token <API_TOKEN> \
  --http-enabled \
  --https-enabled=false

Clients connecting to the MCP server must then include the token in the Authorization header. This token is separate from the EventSourcingDB API token and only controls access to the MCP server.

Once the MCP server is running, you can connect it to an LLM. For details on how to configure the connection, see Connecting to an LLM.