insiders

The X-MCP-Insiders opt-in header: InsidersConfig and parse_insiders.

See also

Insiders header, routing and audit

Parser for the experimental X-MCP-Insiders opt-in header.

The header is a single, self-contained value supplied by the HTTP client: the server never reads insiders state from the environment or from disk. Its grammar is deliberately forgiving so a typo can never break a request – every problem is reported on InsidersConfig (unknown_keys / malformed) and ignored for behaviour. Nothing in this module performs I/O, so the whole surface is unit-testable.

Grammar (comma separated, case-insensitive, - and _ are equivalent):

<missing>

disabled

""

disabled

false

disabled (also 0 / off / no)

true

enabled, every feature at its default (1/on/yes)

model-routing=false

enabled, model-routing overridden to False

model-routing

enabled, model-routing overridden to True

k=v, k2=v2

enabled, each key overridden individually

Keys that are not registered in features.INSIDERS_FEATURES are recorded in unknown_keys and otherwise ignored, so a client can never activate a feature the server does not know about. An unparsable value is recorded in malformed and applies no override – it never raises and never switches the header off. The surface is on whenever the header is present and non-empty; only a bare false-style token, an empty header or a header longer than max_length switches it off.

novelai_image_mcp.insiders.INSIDERS_HEADER = 'X-MCP-Insiders'

Canonical spelling of the opt-in header.

class novelai_image_mcp.insiders.InsidersConfig(enabled=False, features=<factory>, unknown_keys=frozenset({}), malformed=frozenset({}))[source]

Bases: object

Parsed insiders state for one request.

features holds only the overrides the header made for registered features, so an absent key means “use the registered default”. unknown_keys and malformed are diagnostic only: they never change behaviour and exist so an operator can see a typo instead of silently losing the opt-in.

Parameters:
enabled: bool = False
features: Mapping[str, bool]
unknown_keys: frozenset[str] = frozenset({})
malformed: frozenset[str] = frozenset({})
classmethod disabled()[source]

Return the state used when the header is absent or unusable.

Return type:

InsidersConfig

novelai_image_mcp.insiders.parse_insiders(raw, *, max_length=4096)[source]

Parse an X-MCP-Insiders header value into an InsidersConfig.

Parameters:

  • raw (str | None) – The raw header value, or None when the header is absent.

  • max_length (int) – Largest accepted header length. Anything longer is treated as disabled and recorded in malformed.

Returns:

The parsed configuration. Invalid entries are recorded in unknown_keys / malformed and otherwise ignored.

Return type:

InsidersConfig