Skip to content

Behavior notes and limits

Conventions that hold across the whole tool surface, and limits worth knowing before you rely on a result.

Calls and arguments

  • Unknown arguments are refused, not ignored. A call carrying a top-level argument the tool does not declare fails with the same error as a missing required argument, naming the argument, the one you probably meant (for example gateway_logs search or filter suggests contains) and what the tool takes. This applies to calls from MCP clients and to calls arriving from other gateways, before any other check runs. _meta is allowed, and the contents of declared object arguments (api_call query and body, settings and similar) are not checked.
  • policy_explain explains the call you describe. It takes tool and arguments; any other top-level key is refused, naming the right one. The response carries argumentsEvaluated, so you can see exactly which call was explained.
  • Every refusal says how to fix it. See Refusals and remediation.
  • Every mutating tool supports dryRun: true, and dry runs are checked by the same gates as real calls, including ownership of inherited resources, the redundancy role and the name echo.

Results

  • Non-finite numbers are strings. tag_read, tag_browse, tag_history and db_query return NaN and infinities as "NaN", "Infinity" and "-Infinity", so one such value cannot make a whole response unreadable.
  • Bounded reads say they are bounded. Database results report rowCount, truncated and maxRows; the dependency graph reports what it parsed and skipped; deploy_apply reports rollbackArmed and integrityChecked; gateway_logs returns hasMore and a cursor. Read these fields before treating a short result as complete.
  • A refusal is never an empty result. Under per-key read scoping, a read outside the key's lists is refused, not answered with "not found".
  • tag_history takes historian paths, not tag paths. Each entry must carry the histprov component (histprov:<provider>:/drv:<driver>:/tag:<path>). A [provider]Folder/Tag path is refused, naming the entry and pointing at history_browse, which produces the right form.
  • gateway_logs is a query, not a live tail. See gateway_logs.
  • Log reads mask session cookies (Cookie, Set-Cookie, JSESSIONID) and every exact occurrence of this module's API tokens and gateway API key.

Projects and inheritance

  • deploy_export_for_git exports only what a project defines. Inherited resources belong in the repository of the project that defines them. Their count is reported as inheritedExcluded (with inheritsFrom) in the response and in the zip's own deploy-manifest.json.
  • deploy_diff compares a baseline carrying inheritedExcluded against the project's own resources only, and any other baseline against the merged set, reporting which as liveSideOwnResourcesOnly.
  • project_manifest and deploy_diff read the project's ancestors too, so a key narrowed to a child project needs its parents in resourceReadAllowlist for those two tools.
  • deploy_apply takes an optional sha256 of the zip. It is checked against the decoded bytes and the call is refused on mismatch rather than half-applied. The response carries integrityChecked, and an integrityNote when no digest was given. This detects a damaged zip; it does not repair one.
  • deploy_apply does not validate script or JSON content. Use project_resource_write when you need write-time validation. See Writing project resources.
  • view_patch keeps null-valued keys. A Perspective view stores an unset param or custom key as an explicit null. Dropping it would leave its property configuration behind, and every binding reading it would resolve against a missing path with no error logged.

Settings

  • API keys must be unique. Keys sharing a name or a token are disabled at load, with a WARN, until they are made unique.
  • Bare tool-family allowlist entries are flagged. An entry such as security/, config or api logs a WARN, because it also covers a project of that name.
  • Settings saves are checked for conflicting edits. Two administrators cannot silently overwrite each other's changes. A settings tab left open across a module restart gets one 409 response and needs a reload.
  • Profiles that match nothing are reported at startup with a WARN per pattern. See Tool profiles.
  • Script endpoints register only at startup. See Script endpoints.

Clients

  • The server is stateless. GET on the MCP endpoint returns 405; there is no event stream, and the server does not push tool-list changes. Reconnect a client after its key's profile, the enabled providers or the declared script endpoints change.

Network

  • IP-based controls use the direct peer address. Behind a reverse proxy, localhostOnly no longer restricts anything and the failed-authentication backoff is shared by all clients. See Security.

Features without a dedicated tool

Report schedules have no dedicated tool. Where the gateway's REST API covers a feature, reach it through api_call, or expose a project function for it as a script endpoint.