Configuration

Environment variables#

Variable	What it does
`TOOLPORT_CLIENT_ID`	Identifies the client for live profile resolution. Written on Connect.
`TOOLPORT_PROFILE`	Pins the client to one profile. Unset follows the active profile.
`TOOLPORT_DISCOVERY`	`lazy`, `full` or `grouped`. Per-client override of the global setting.
`TOOLPORT_REGISTRY`	Path to the registry file. Defaults to a stable per-user path.
`TOOLPORT_DATA_DIR`	Overrides the whole Toolport data directory.
`TOOLPORT_RESULT_BUDGET`	Caps oversized tool results at this many bytes. `0` disables it.
`TOOLPORT_HTTP`	Port for HTTP/OpenAPI mode instead of stdio. Prefer the `--http` flag in scripts.
`TOOLPORT_HTTP_HOST`	Bind address. Default `127.0.0.1`.
`TOOLPORT_HTTP_TOKEN`	Bearer token. Required for every bind.
`TOOLPORT_METRICS`	`1` enables Prometheus `GET /metrics` on the HTTP surface.
`TOOLPORT_DEBUG`	`1` enables per-request trace logging.
`TOOLPORT_GATEWAY_TOPOLOGY`	`daemon` or `legacy` for one client launch.
`TOOLPORT_CODE_MODE`	`1` force-enables code mode.
`TOOLPORT_SEMANTIC`	`on` blends embedding similarity into tool search.
`TOOLPORT_EMBED_ENDPOINT`, `TOOLPORT_EMBED_MODEL`	The `/v1/embeddings` endpoint and model for semantic search.
`TOOLPORT_EMBED_KEY`, `TOOLPORT_EMBED_BLEND`	Optional endpoint auth and blend setting.
`TOOLPORT_SECRET_KEY`	Passphrase for the encrypted `secrets.enc` vault (headless).
`TOOLPORT_SECRET_<KEY>`	Injects a server secret directly (headless).
`TOOLPORT_ALLOW_BARE_SECRET_ENV`	`1` lets a bare `<KEY>` env var satisfy a secret.

Every TOOLPORT_* name still accepts the pre-rename CONDUIT_* alias, so CONDUIT_HTTP_TOKEN keeps working. Prefer TOOLPORT_* in new configs.

Minimal registry.json#

A valid headless registry needs profiles and activeProfileId, not just servers:

{
  "version": 1,
  "servers": [
    {
      "id": "stripe",
      "name": "Stripe",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@stripe/mcp"],
      "env": [{ "key": "STRIPE_SECRET_KEY", "secret": true }],
      "source": "manual"
    }
  ],
  "profiles": [
    { "id": "default", "name": "Default", "enabledServerIds": ["stripe"] }
  ],
  "activeProfileId": "default"
}

Secret resolution order#

When a server marks env[].secret: true:

TOOLPORT_SECRET_<KEY> in the process env.
<KEY> in the process env, only when TOOLPORT_ALLOW_BARE_SECRET_ENV=1.
Encrypted secrets.enc, when TOOLPORT_SECRET_KEY is set.
The OS keychain (desktop).

Updated Sep 25, 2026