Skip to content

Known quirks and open questions

Section 11 · From docs/MCP_INTERNALS.md on GitHub

Found while writing this guide, and still present after the fixes that followed it (each re-checked by running it). The earlier list also had items about annotation hints for cloud_access and exec, unprefixed names resolving in-process, unvalidated prefixes, the truncated_chars count, completions bypassing middleware, cache hits skipping the policy, the fastmcp and SDK flavors' Origin handling, the resource decorators' missing parameters, native 2026 header leniency, token-spec parsing, and two redaction false positives ("SECRET" asset counts redacted under standard, Azure subscription ids labelled aws_account_id under strict). Those are fixed and covered by tests.

  1. register_into(prefix=...) (adapters/init.py 124-125) assigns layer.prefix on the shared layer. One layer therefore cannot be mounted under two prefixes, and this path skips the constructor's prefix validation: register_into(layer, server, prefix="bad:") was accepted, and the error only appeared when the tool list was rendered (ValueError: Invalid exposed tool name 'bad:echo').
  2. A completion that the policy denies or rate-limits raises out of _completion_terminal (layer.py 694), so the adapters answer with a JSON-RPC error (-31001 / -31029), while an unknown or hidden ref gets an empty completion. In a run with a one-per-minute limit on a template, the second layer.complete(...) raised RateLimitedError -31029 "Rate limit exceeded for completion 'test://items/{item_id}' (1/minute); retry in 60.0s". Arguably fine (the spec asks for rate limiting), but clients may not expect errors from completions.
  3. Tool and prompt wire dicts always contain description, empty or not (core.py 449, 589); the spec allows omitting it.
  4. cloudg mcp config --client claude-desktop --transport http --token-env VAR still produces an mcp-remote entry with no env block (cli.py 513-519); whether ${VAR} expands depends on the environment Claude Desktop gives npx. Not tested.
  5. A two-field spec is read from the right, so --auth-token abc:def means token abc with role def (auth.py 149). That is the documented rule, but an operator with a colon in a token gets a silently different token, with no error to warn them.
  6. test_catalog_registry.py (line 47) still requires openWorldHint false for every catalog tool without cloud_access, while the derivation in 3.5 now makes an exec-only tool open-world. No catalog tool has exec without cloud_access today, so the test passes; a future offline-scanner tool would trip it.