Skip to content

The developer server’s mode decides your tool list

Filesystem, API, or auto — one mode wins at startup, and each unlocks a different, non-overlapping slice of the developer server’s tools.

The developer server resolves exactly one mode when it starts — filesystem, or api — and that single mode, not a per-call choice, decides which of its tools actually register.

How auto resolves

With KYWI_MCP_MODE unset or set to auto, the server tries a writable local config file first: if KYWI_CONFIG_PATH points at a file it can write to, mode is filesystem. Otherwise, if both KYWI_API_URL and KYWI_MCP_DEV_KEY are set, mode is api. If neither condition holds, the server throws at startup rather than starting with an empty tool list.

.env — three ways to start itbash
# resolves to filesystem — the writable file wins even if API vars are also set
KYWI_CONFIG_PATH=./kywi.config.ts
KYWI_MCP_MODE=auto

# resolves to api — no local file, both API vars present
KYWI_API_URL=http://localhost:3000/api/v1
KYWI_MCP_DEV_KEY=kywi_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
KYWI_MCP_MODE=auto

# forces the mode outright — skips detection
KYWI_MCP_MODE=filesystem

What each mode actually unlocks

The read-only config tools (get_config_summary, get_content_types, and their siblings) register in either mode. Past that, the two modes unlock genuinely different tools: filesystem mode adds the config-mutation tools that edit kywi.config.ts directly; api mode adds the API-key management tools. Scaffolding tools sit outside this split entirely — they register whenever a baseUrl is configured, in either mode. There's no mode that has both config-mutation and API-key tools at once.

In filesystem mode the list tools come back empty

In filesystem mode the read-only tools don't parse your config — they run regular expressions over it as text. get_content_types looks for defineContentType( followed by a quoted string; get_themes looks for defineTheme( followed by a quoted string. Both helpers are real exports and a real config calls them, but each takes a single object argument and never a quoted name, so neither pattern can ever match. Both tools return an empty list against a config declaring a dozen types. get_themes is not the exception here — it carries the identical regex, and so do get_modules and get_plugins.

get_config_summary is the one that answers correctly, because it counts the bare call with nothing after the parenthesis to match. Its content-type count is right at the same moment the tool that lists them by name reports none — the number and the list disagree, and the number is the one to believe.

For an accurate list, read contentTypes out of the config object directly, or use the site server's list_content_types tool against the running site. See Designing a content type for how types are actually declared.