Chronicle.MCP

The Chronicle MCP server connects an AI agent to a running Cratis Chronicle event-sourcing database over the Model Context Protocol. Point your agent at a Chronicle server and it can explore the domain, operate observers and jobs, and turn plain-language requests into Chronicle artifacts — always grounded in the store's real schema.

Because the server talks to Chronicle directly, it works no matter which Chronicle client language your application uses — .NET, TypeScript, Kotlin/Java, or Elixir. Any MCP-capable tool can use it. See the Documentation for the full guide.

Using

The Chronicle MCP server leverages Stdio and is packaged as a container. In your tool, configure it using that.

Releases are also listed in the official MCP Registry as io.github.Cratis/chronicle-mcp, using the same versioned Docker Hub image. The listing starts the server in the read-only profile; job control needs the Mutation profile and an authorization policy.

Note: You must have a Chronicle server running.

Example: VSCode

In VSCode you would do this by adding a tool to your agent. This can done either by adding it to the global user settings or through an mcp.json file in the .vscode folder of your project.

For the global user settings, you simply do the following:

"mcp": {
    "servers": {
        "Chronicle": {
            "type": "stdio",
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-eCratis__Chronicle__Mcp__ConnectionString=chronicle://host.docker.internal:35000",
                "cratis/chronicle-mcp"
            ]
        }
    }
}

Note: To configure the connection string for Chronicle you pass it an environment variable; Cratis__Chronicle__Mcp__ConnectionString running locally - on MacOS and Windows the host machine is found at host.docker.internal.

For a local mcp.json file, its almost the same:

{
    "servers": {
        "Chronicle": {
            "type": "stdio",
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-eCratis__Chronicle__Mcp__ConnectionString=chronicle://host.docker.internal:35000",
                "cratis/chronicle-mcp"
            ]
        }
    }
}

You can see this in action in the mcp.json in this repository.

Note: The cratis/chronicle-mcp is a multi CPU architecture image supporting both x64 and arm64 automatically.

Configuration

Configuration is optional. The MCP server works out of the box with sensible defaults suitable for local development:

• Connection String: chronicle://host.docker.internal:35000
• Credentials: Development client ID (chronicle-dev-client) and secret (chronicle-dev-secret)
• Profile: ReadOnly — mutating tools are not listed or callable.

If you need to customize any settings, the MCP server can be configured entirely on its own and is also compatible with the Cratis CLI. For any value you do not set explicitly, the server resolves it in this order:

1. Explicit MCP options (environment variables / appsettings.json).
2. The CHRONICLE_CONNECTION_STRING environment variable.
3. The active context in the CLI configuration at ~/.cratis/config.json.
4. Built-in development defaults.

When client credentials are used, the server obtains and caches OAuth tokens in ~/.cratis/tokens, the same location used by the CLI, so tokens are shared between the two.

All options live under the Cratis:Chronicle:Mcp configuration section. As environment variables they use the Cratis__Chronicle__Mcp__ prefix:

Job control requires the Mutation profile and a matching grant for the deployment principal, store, namespace, operation, and job ID. A connection string or Chronicle credentials alone never enable mutations. Keep credentials in environment variables or a secret store, never in server.json or a committed appsettings.json. See Deployment profiles for policy examples and denial codes.

Prompts / Tools

The server exposes the following tools. Every tool defaults the event store and namespace to the configured defaults when you do not specify them, so you can ask high-level questions and only mention a store or namespace when you need a specific one.

The tools come in two complementary sets: operate-side tools for inspecting and operating a live store, and design-time tools that turn natural language into Chronicle artifacts grounded in the store's real schema. See the Documentation folder for a full guide, and How it works for the split.

Operate-side

Design-time

The server also exposes MCP prompts — describe_system, suggest_next_event_types, and query_system — that package these workflows for clients that surface prompts (for example as slash commands).

You can ask it things like:

• List all event stores
• List all event types in the [put name here] event store
• List all observers in the [put name here] event store and namespace [put namespace here]
• Show me the events in the [put name here] event store
• Are there any failed partitions?
• What observers in the [put event store name here] use event type [put event type name]
• List all jobs in the [put event store name here] event store
• Show me job [put job id here] in the [put namespace name here] namespace
• What steps does job [put job id here] have?
• Stop / Resume / Delete job [put job id here] (requires an authorized Mutation deployment)

And design-time questions like:

• Describe the system in [put event store here] — and tell me its story
• What event types should I introduce next for the system in [put event store here]?
• Show all [put concept here] with all details (runs an ad-hoc projection)
• Show me all the [put concept here] registered (scaffolds a read model + projection)
• What fields does the [put event type here] event have?
• What events are we writing that nothing reads?
• Give me a catalog of our [put area here] events and who reads them
• Why does [put entity here] show as [put state here]?

Local development

Using VSCode, the mcp.json in the .vscode folder of this repository is automatically supported. Local development defaults to ReadOnly. Open it and click the Start button:

During development, compile and click the Restart button when having the mcp.json open:

Chronicle

To get Chronicle running, there is a docker-compose.yml file in the Source folder. Simply do docker compose up -d and you'll have a Chronicle instance running.

If you want some data, we recommend using our samples and specifically the console to initialize it with some data.

The Cratis ecosystem

This project is part of Cratis — free, MIT-licensed tools for building event-sourced and CQRS applications.

• Chronicle — event-sourcing database and runtime. Orleans-based kernel, pluggable storage (MongoDB default; PostgreSQL, SQL Server, SQLite, in-memory), language-agnostic gRPC contracts. Docs
• Chronicle clients — first-class .NET SDK, plus TypeScript, Kotlin/Java, and Elixir; Python coming soon (pre-alpha). AI agents connect through the Chronicle MCP server (this repository).
• Arc — opinionated CQRS framework for ASP.NET Core with commands, queries, validation, authorization, and TypeScript proxy generation. Works without event sourcing. Docs
• Components — React components aligned with Arc patterns. Docs
• CLI + Workbench — inspect and diagnose Chronicle from the terminal or the browser. Docs
• Model-first layer (experimental) — Studio, Screenplay, Stage, Scene, Prologue
• Supporting — Fundamentals, Specifications, Synopsis, Lens, Narrator, and free AI tooling (preview); Ensemble coming soon (pre-release)
• Samples — runnable event sourcing and CQRS samples for the whole stack

Everything Cratis publishes today is MIT licensed and free to use.