Configuration

ToolMesh is configured entirely via environment variables and YAML files.

Environment Variables

MCP Server

Variable	Default	Description
`TOOLMESH_PORT`	`8123`	Host port (Docker mapping; internally always 8080)
`TOOLMESH_TRANSPORT`	`http`	Transport: `http` or `stdio`
`TOOLMESH_CORS_ORIGINS`	(empty)	Allowed CORS origins
`TOOLMESH_AUTH_PASSWORD`	(empty)	Single-user OAuth password
`TOOLMESH_API_KEY`	(empty)	Static API key

Audit

Variable	Default	Description
`AUDIT_STORE`	`log`	`log` (slog) or `sqlite`
`AUDIT_RETENTION_DAYS`	`90`	Retention for SQLite store

Authorization

Variable	Default	Description
`OPENFGA_API_URL`	`http://localhost:8080`	OpenFGA API endpoint
`OPENFGA_STORE_ID`	(empty)	OpenFGA store ID
`OPENFGA_MODE`	`bypass`	`bypass` (no authz) or `restrict` (enforced)

Timeouts

Variable	Default	Description
`TOOLMESH_MCP_TIMEOUT`	`120`	HTTP client timeout for MCP backends (seconds)
`TOOLMESH_EXEC_TIMEOUT`	`120`	Tool execution timeout (seconds)

Logging

Variable	Default	Description
`LOG_LEVEL`	`debug` / `info`	Log verbosity
`LOG_FORMAT`	`json`	`json` or `text`
`DEBUG_BACKENDS`	(empty)	Comma-separated backend names for debug logging
`DEBUG_FILE`	(empty)	Path to debug log file

Credentials

Credentials are set as env vars with CREDENTIAL_ prefix:

CREDENTIAL_GITHUB_TOKEN=ghp_xxxxx
CREDENTIAL_STRIPE_KEY=sk_live_xxxxx
CREDENTIAL_MEMORIZER_API_KEY=sk-mem-xxxxx

Configuration Files

backends.yaml

Defines which backends ToolMesh connects to:

backends:
  # MCP backend
  - name: memorizer
    transport: http
    url: "https://memorizer.example.com/mcp"
    api_key_env: "MEMORIZER_API_KEY"

  # REST backend via DADL
  - name: github
    transport: rest
    dadl: /app/dadl/github.dadl
    url: "https://api.github.com"

Tools are automatically exposed with a backend prefix (e.g., memorizer_retrieve_knowledge, github_list_repos).

users.yaml

Multi-user configuration for OAuth:

users:
  - username: alice
    password: "$2a$12$..."
    company: acme
    plan: pro
    roles: [admin]

apikeys.yaml

API key definitions:

keys:
  - key_hash: "$2a$12$..."
    username: ci-bot
    company: acme
    plan: standard
    roles: [read]
    caller_id: github-actions

caller-classes.yaml

Maps caller IDs to trust classes:

classes:
  trusted:
    - claude-code
    - claude-desktop
  standard:
    - partner-*
  # Everything else → "untrusted"