Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration reference

Everything is configured with environment variables. The server checks all of them at startup and refuses to start with a list of every problem it found, so a typo never leaves it half configured.

General rules:

  • An empty value counts as unset.
  • Every variable can also be read from a file by appending _FILE to its name, for example OAUTH_SIGNING_KEY_FILE=/run/secrets/oauth_signing_key. A value set directly wins over the file, and a trailing newline in the file is ignored. Use this for secrets with Docker or Kubernetes secrets.
  • Booleans accept true, false, 1, 0, yes, no, on and off, in any case.
  • Lists are comma separated; spaces around names are ignored.

Server and HTTP

VariableRequiredDefaultExampleDescription
PUBLIC_URLyeshttps://crm-mcp.example.comExternal base URL clients use, without a path. Must be https; http is accepted only for localhost
BIND_ADDRno0.0.0.0:8443127.0.0.1:8443Listen address. It must listen on loopback (0.0.0.0 does) so --healthcheck can reach 127.0.0.1
TLS_CERT_PATH, TLS_KEY_PATHno/certs/fullchain.pem, /certs/privkey.pemPEM certificate chain and private key. Both or neither; reloaded automatically when the files change. See TLS and public access
INSECURE_HTTPnofalsetrueServe plain HTTP. Only when TLS is terminated in front of the server on a network you trust
ALLOWED_ORIGINSnohttps://app.example.comExtra Origin values accepted on MCP requests, comma separated. The PUBLIC_URL origin is always allowed
TRUSTED_PROXIESno10.0.0.2,10.0.0.3Proxy IP addresses whose X-Forwarded-For is trusted for sign-in rate limiting

Services

VariableRequiredDefaultExampleDescription
TWENTY_SERVICESnoall (crm)crmServices to run. There is one, crm. An unknown name or an empty list stops startup
TWENTY_READ_ONLYnononecrm or allServices whose write tools are hidden and refused, on their own endpoint and under /mcp. An unknown name stops startup. See Security
TWENTY_COMBINEDnotruefalseServe the combined endpoint /mcp. With false, /mcp returns 404

OAuth

VariableRequiredDefaultExampleDescription
OAUTH_SIGNING_KEYyesoutput of openssl rand -hex 32Key that signs OAuth tokens and seals each person’s Twenty API key inside them, at least 32 bytes. Changing it signs everyone out

People sign in with their own Twenty API key, so there is no OAUTH_ADMIN_PASSWORD, and MCP_AUTH_TOKEN must not be set: the server refuses to start with it.

Twenty

VariableRequiredDefaultExampleDescription
TWENTY_API_URLnohttps://api.twenty.comhttps://crm.example.comYour Twenty server’s address, without /rest. Must be https, or http to a loopback address only; no credentials, query or fragment. Leave it unset for Twenty Cloud. Changing it signs everyone out
TWENTY_DEFAULT_CURRENCYnoUSDGBPThree-letter ISO 4217 code for opportunity amounts given without one. Upper-cased; anything else stops startup

Logging, metrics and audit

VariableRequiredDefaultExampleDescription
LOG_LEVELnoinfoinfo,mcp_twenty_crm_records=debugLog filter in tracing syntax. Targets: mcp_twenty_crm, mcp_twenty_crm_records, mcp_server_core. The audit target always stays on at info
LOG_FORMATnojsonprettyjson or pretty
DEBUGnofalsetrueDebug logging for mcp_twenty_crm* and mcp_server_core: the arguments of read tools (search words, filters), Twenty request paths with record ids, status codes, timings and tool error details. Never API keys or response bodies
DEBUG_UNSAFE_LOG_CONTENTnofalsetrueAlso logs full tool results and Twenty response bodies, which puts your CRM records in the logs. Never in production. API keys are never logged
METRICS_ADDRno0.0.0.0:9090Starts a separate plain-HTTP Prometheus listener. Keep it on an internal network
OTEL_EXPORTER_OTLP_ENDPOINTnohttps://otel.example.comExports traces over OTLP/HTTP. The standard OTEL_EXPORTER_OTLP_HEADERS is honoured. Nothing is exported unless it is set
AUDIT_LOG_PATHno/audit/audit.jsonlFile every write tool call is appended to as one JSON line (created with mode 0600). Audit lines are always logged too. See Security

A complete example

PUBLIC_URL=https://crm-mcp.example.com
OAUTH_SIGNING_KEY_FILE=/run/secrets/oauth_signing_key
TWENTY_API_URL=https://crm.example.com
TWENTY_DEFAULT_CURRENCY=GBP
TLS_CERT_PATH=/certs/fullchain.pem
TLS_KEY_PATH=/certs/privkey.pem
AUDIT_LOG_PATH=/audit/audit.jsonl
LOG_FORMAT=json