---
title: Getting started
editUrl: https://github.com/Cratis/Chronicle.Mcp/edit/main/Documentation/getting-started.md
description: 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.
---

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

- A running Chronicle server. If you do not have one, the [`docker-compose.yml` in the repository](https://github.com/Cratis/Chronicle.Mcp/blob/main/Source/docker-compose.yml) 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

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:

```json
{
    "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](/chronicle-mcp/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](/chronicle-mcp/deployment-profiles/).

## 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](/chronicle-mcp/design-time/describe-system/) and tells the system's story.
- "Show all employees with all details" → an [ad-hoc projection](/chronicle-mcp/design-time/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](/chronicle-mcp/design-time/suggest-next-event-types/).
- "Show me all the users registered" → the agent resolves the event types, then proposes a read model with [read-model scaffolding](/chronicle-mcp/design-time/read-model-scaffolding/).
- "What events are we writing that nothing reads?" → an [unconsumed-event audit](/chronicle-mcp/design-time/unconsumed-event-audit/).
- "Why does this order show as cancelled?" → a [causal trace](/chronicle-mcp/design-time/causal-trace/) of the order's history.

## Where to go next

- [Configuration](/chronicle-mcp/configuration/) — connect to a secured server, share the CLI's context, or run without Docker.
- [Deployment profiles](/chronicle-mcp/deployment-profiles/) — keep read-only access or grant bounded job-control authority.
- [How it works](/chronicle-mcp/concepts/) — the two modes and why every design-time suggestion is grounded in real schema.
- [Design-time capabilities](/chronicle-mcp/design-time/) — the full set of generative and advisory tools.