Skip to content
Cratis

Getting started

By the end of this page you will have the Chronicle MCP server running inside your agent and answering questions about a live Chronicle store.

Prerequisites

Section titled “Prerequisites”
  • A running Chronicle server. If you do not have one, the docker-compose.yml in the repository brings one up with docker compose up -d.
  • An MCP-capable agent (for example VS Code with an agent extension, or any client that speaks the Model Context Protocol over stdio).
  • Docker, to run the pre-built cratis/chronicle-mcp image.

Wire it into your agent

Section titled “Wire it into your agent”

The server speaks MCP over stdio and ships as a container. Configure your agent to launch it. In VS Code, add it to your user settings or to a .vscode/mcp.json in your project:

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

On macOS and Windows the host machine is reachable from the container at host.docker.internal. The connection string is the only value most setups need to change — everything else has a working local-development default. See Configuration for the full resolution order and authentication.

This configuration starts in the safe ReadOnly profile. You can inspect jobs, but stop_job, resume_job, and delete_job are not listed or callable. To enable authorized job control, configure a Mutation deployment profile.

Ask your first questions

Section titled “Ask your first questions”

Once the server is connected, your agent can reach the store. Start with the operate-side capabilities to confirm connectivity:

  • “List all event stores.”
  • “What event types are registered?”
  • “Are there any failed partitions?”

Then try the design-time capabilities, which turn a plain request into a grounded artifact:

  • “Describe the system in this event store” → the agent deduces entities and lifecycles with describe the system and tells the system’s story.
  • “Show all employees with all details” → an ad-hoc projection folds the events into current state on demand.
  • “What event types should I introduce next?” → grounded gap findings from suggest the next event types.
  • “Show me all the users registered” → the agent resolves the event types, then proposes a read model with read-model scaffolding.
  • “What events are we writing that nothing reads?” → an unconsumed-event audit.
  • “Why does this order show as cancelled?” → a causal trace of the order’s history.

Where to go next

Section titled “Where to go next”
  • Configuration — connect to a secured server, share the CLI’s context, or run without Docker.
  • Deployment profiles — keep read-only access or grant bounded job-control authority.
  • How it works — the two modes and why every design-time suggestion is grounded in real schema.
  • Design-time capabilities — the full set of generative and advisory tools.

Community: Discord