Skip to content
Cratis

Configuration

Configuration is optional. The server works out of the box with defaults suited to local development:

  • Connection string: chronicle://localhost:35000
  • Credentials: the development client id (chronicle-dev-client) and secret (chronicle-dev-secret)
  • Event store / namespace: default / Default
  • Deployment profile: ReadOnly — job-control tools are not registered.

You only set values when you need to point at a different server or authenticate against a secured one.

Resolution order

Section titled “Resolution order”

For every value the server has not been given explicitly, it resolves in this order, first match wins:

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

Because step 3 reads the same file the Cratis CLI writes, a store you have already set up with cratis context create is picked up automatically — no separate configuration.

Options

Section titled “Options”

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

OptionEnvironment variableDescription
ProfileCratis__Chronicle__Mcp__ProfileReadOnly (default) or Mutation. An unknown value prevents startup.
Authorization.PrincipalCratis__Chronicle__Mcp__Authorization__PrincipalIdentity this process acts for. Required and non-blank in Mutation.
Authorization.ExpiresAtCratis__Chronicle__Mcp__Authorization__ExpiresAtPolicy expiration as an ISO-8601 timestamp. Required and in the future at mutation startup.
Authorization.RevokedPrincipalsCratis__Chronicle__Mcp__Authorization__RevokedPrincipals__0Indexed list of revoked principals. Defaults to empty.
Authorization.GrantsCratis__Chronicle__Mcp__Authorization__Grants__0__Principal (and other grant fields)Indexed grants naming principal, store, namespace, operations, and targets. Defaults to empty; Mutation requires a grant for its principal.
ConnectionStringCratis__Chronicle__Mcp__ConnectionStringThe Chronicle connection string. Defaults to chronicle://localhost:35000.
ContextCratis__Chronicle__Mcp__ContextThe CLI context to read connection details from. Defaults to the active context.
UseCliConfigurationCratis__Chronicle__Mcp__UseCliConfigurationSet to false to ignore ~/.cratis/config.json entirely.
ClientId / ClientSecretCratis__Chronicle__Mcp__ClientId / ...__ClientSecretClient credentials for authentication. Defaults to development credentials.
ApiKeyCratis__Chronicle__Mcp__ApiKeyAn API key to authenticate with, as an alternative to client credentials.
EventStoreCratis__Chronicle__Mcp__EventStoreThe default event store used by tools when none is specified. Defaults to default.
NamespaceCratis__Chronicle__Mcp__NamespaceThe default namespace used by tools when none is specified. Defaults to Default.

Every tool defaults the event store and namespace to these configured values, so you can ask high-level questions and only name a store or namespace when you need a specific one.

See Deployment profiles for the complete grant format, wildcard rules, revocation, and denial codes. Profile and authorization settings do not fall back to CLI contexts or development credentials.

Authentication

Section titled “Authentication”

Keep credentials in environment variables or a secret store, never in server.json or a committed appsettings.json. Chronicle authentication does not authorize MCP mutations.

The server authenticates the same way the CLI does, and shares its token cache:

  • Client credentials (OAuth): when the connection string carries a client id and secret (or you set ClientId/ClientSecret), the server obtains an OAuth token from the server’s token endpoint, derived from the connection’s own address. Tokens are cached on disk under ~/.cratis/tokens, the same location the CLI uses, so the two share credentials.
  • API key: set ApiKey (or embed apiKey= in the connection string) to authenticate with a static key instead.

The token endpoint is taken from the connected server’s address; there is no separate management-port setting. If you are upgrading from an older release that had a ManagementPort option, you can remove it — it no longer has any effect.

Connect timeout

Section titled “Connect timeout”

Set CHRONICLE_CONNECT_TIMEOUT_SECONDS to override the default 5-second connect timeout when reaching a slow or remote server.

Community: Discord