Configuration #

The server is configured entirely through environment variables, set in your MCP client’s server config (the env block).

Authentication #

Two modes; the token wins if both are set:

Personal access token (recommended) — scoped, revocable, and keeps your password out of config files. Create one at Dashboard → Developers → API tokens.

"env": {
  "MICROBOOKS_TOKEN": "<personal access token>"
}

Email + password — the server logs into the auth service itself and manages the token lifecycle (lazy login, proactive refresh, re-login on persistent 401s).

"env": {
  "MICROBOOKS_EMAIL": "you@example.com",
  "MICROBOOKS_PASSWORD": "..."
}

Reference #

Variable	Default	Purpose
`MICROBOOKS_TOKEN`	—	Personal access token (recommended; overrides email/password)
`MICROBOOKS_EMAIL` / `MICROBOOKS_PASSWORD`	—	Auth-service login, when no token is set
`MICROBOOKS_API_URL`	`https://api.microbooks.io`	Books API base URL
`MICROBOOKS_AUTH_URL`	value of `MICROBOOKS_API_URL`	Auth service base URL, if different
`MICROBOOKS_TIMEOUT`	`30`	HTTP timeout in seconds
`MICROBOOKS_REFRESH_MINUTES`	`50`	Proactive re-login interval (email/password mode only)
`MICROBOOKS_CONFIRM_POST`	off	When truthy, `post_transaction` asks you to confirm interactively (via MCP elicitation) before committing
`MICROBOOKS_PERIOD_CLOSE`	off	Register the three period-close tools
`MICROBOOKS_RECYCLE_BIN`	off	Register the two recycle-bin tools
`MICROBOOKS_SETUP_TOOLS`	off	Register the ten `manage_*` setup tools

Any of 1, true, yes or on counts as truthy.

Enabling tool groups #

Fifteen tools are enabled by default. The three flags above add up to fifteen more. A worked config for an operator who wants period close and the chart-of-accounts tools, with confirmation before anything is committed:

{
  "mcpServers": {
    "microbooks": {
      "command": "metafrasi-mcp",
      "env": {
        "MICROBOOKS_API_URL": "https://api.microbooks.io",
        "MICROBOOKS_TOKEN": "<personal access token>",
        "MICROBOOKS_CONFIRM_POST": "1",
        "MICROBOOKS_PERIOD_CLOSE": "1",
        "MICROBOOKS_SETUP_TOOLS": "1"
      }
    }
  }
}

A group left off is invisible to the assistant rather than merely refused, so enabling one is a decision only you can make. Tool groups covers what each adds and the risks worth weighing.

Confirmation prompts need a capable client #

MICROBOOKS_CONFIRM_POST, post_period_close and destroy_recycled ask you to confirm through MCP elicitation — a prompt your client shows you, not a question put to the model.

If your client does not support elicitation, those operations fail with a clear error telling you to use dry_run=true or a client that does. They do not fall through and commit, and they no longer take the session down with them.

Secrets stay in the env block. The server never logs credential values, and startup errors name only the missing variable. Keep the config file itself out of version control.