Glossary

Canonical domain terms for this project. Code and docs use these terms; _Avoid_ synonyms are banned in new names. Conceptual terms are defined here; code-backed terms are defined at their code home and autolinked from here; principles and invariants are defined in their prose home and pointed at from here. Other documents point at a term's home instead of redefining it.

This glossary describes what is: an entry is written when the thing its term names is real. A Redefinition in flight — <date> → <topic ID>: line under a term head means a topic is changing that definition; what stands below it is still the current one.

A

acceptance

Wymcp.Response.send_accepted/1

• Avoid: 202-and-drop, ack / acknowledgement, empty response, drop

action

A named operation within a tool, selected by the "action" key in a call's arguments; atom internally, string on the wire. Header binding mirrors it into Mcp-Param-Action on every modern tools/call. The help tool's action parameter also holds an action name — a reference to this concept, not a second meaning. The elicitation-response "action" field (accept/decline/cancel) is an unrelated, spec-fixed wire collision.

action schema

Wymcp.Tool.action_schema/0

• Avoid: action definition ("definition" names the tool-level wire object), tool schema

action-schema invariant

Wymcp.Tool.Actions

• Avoid: schema-vocabulary invariant, key-coverage invariant, validator-coverage invariant

action summary

Wymcp.Tool.Schema.action_summaries/1

• Avoid: one-liner, one-line description

arguments

The params object of a tools/call request, carrying action + data. Optional on the wire: absent or JSON-null arguments read as the empty object. Its key set is closed: a key other than action/data is rejected by a dispatch gate, and the generated input schema publishes that with additionalProperties: false. Distinct from message validation, which checks the whole JSON-RPC message one layer up.

• Avoid: envelope, tool envelope, call envelope

auth behaviour

Wymcp.Auth

auth check

The wire check that calls the configured Auth behaviour and answers 401 plus the WWW-Authenticate challenge on failure. Implemented by Wymcp.Plugs.Auth; distinct from the Auth behaviour — the consumer contract it calls.

B

behaviour-only tool

A tool module that implements @behaviour Wymcp.Tool by hand instead of use Wymcp.Tool, owing every required callback itself. Tolerated at wire-in by design — the callback-surface check verifies what a declaration promises, not who declared it (Wymcp.Tool.validate_callback_surface!/1); an internal accommodation, not a consumer contract. Wymcp.Help is the framework's only one.

• Avoid: duck-typed tool (for the class — "duck-typing tolerance" survives as the check's posture), behaviour-only module

bounded

Defined in Wymcp.Bound — its moduledoc's rule; Wymcp.Bound.render/1 is the rendering form, Wymcp.Bound.value/1 the line form. Avoid: truncated, clipped, capped, sanitized, safe value (for this concept); budget (for the bound — a token budget is the reader's, and inspect's term budget is its :limit); scrub is the control-character half alone, never the whole

C

callback-surface invariant

Defined in Wymcp.Tool — the callback-surface invariant section.

• Avoid: optional-callback contract, callback completeness rule, strict-optional callback, guarded callback

cell

One derived assertion of a sweep test: one per member, or per pair of members, of the closed lists the test sweeps — a router option, a callback, a (verb × check) pair — named in its describe heading so a failing run names the cell. A cell derives from the list rather than being written by hand, which is what closes the sweep: a new member gets its cell by joining the list. A hand-written test block is a test, not a cell — the word is reserved for the derived kind.

• Avoid: verb–check pair

check-exempt verb

An HTTP verb whose route Wymcp.Router deliberately serves without one named wire check. The shape was designed for a CORS preflight route, which would be exempt from the auth check, because a preflight carries no Authorization header, while the origin and singleton-header checks still ran on it; wymcp serves no such route — browser access is the host's, not wymcp's. The exemption is always per verb and scenario, never blanket: an entry's key is a scenario label from Wymcp.WireCheckInvariantTest's table, so a check with two scenarios, as the origin check has, takes one entry per scenario. There are none: the record is that module's @check_exempt_verbs, empty, each future entry naming its scenario and the reason. Every other cell must answer either that check's rejection or the fallthrough — both read from the marks the router and the shared rejection sender set; an exempt cell must answer neither, so an entry that stops being true fails.

• Avoid: public verb, public route

consumer-authored text

Defined at its code home: the Wymcp.Tool moduledoc, section "Consumer-authored text".

context

Wymcp.Context.t/0 Bare context names the struct. The "context" response key is action context; the third element of a 3-tuple run_action return is hint context.

• Avoid: execution context, call context

D

defaults

Defined at its code home: the Wymcp.Tool moduledoc, section "Action schema format". Distinct from a property's JSON Schema "default" keyword, which reaches a caller only as help text — the framework never reads it, so :defaults is the one default that applies.

• Avoid: default values, fallbacks, fallback values

definition

Wymcp.Tool.build_definition/1

• Avoid: tool spec, descriptor, tool entry, listing

dispatch gate

A check inside Wymcp.Tool.dispatch/3 that rejects a call before the action handler runs, answering in the tool dialect — isError content carrying a help pointer — rather than as a JSON-RPC error. The gates run in one chain and the first to fire answers; the rest surface on the caller's next attempt. Distinct from a wire check, which rejects a request before any tool is reached and whose _Avoid_ list bans "gate" at that layer.

• Avoid: guard, validation step, dispatch check

distilled error

Defined in the Wymcp.JsonRpc moduledoc — the distillation paragraph (the bolded distilled definition: the envelope message plus data.errors, one entry per instance location).

• Avoid: normalized error, full error tree (for this wire shape)

E

elicitation

Wymcp.Context.elicit/4 The elicitation-response "action" field is the wire collision the action entry names; under MRTR it rides inside inputResponses.

error dialect

The error-body convention an HTTP answer speaks. Wymcp has two structured dialects: the JSON-RPC dialect (the enveloped error object every POST answer carries) and the tool dialect (the isError tool-result payload). Each route's errors speak one dialect — the fallthrough's 405 and 404 are one-line text bodies, no dialect at all.

• Avoid: register, error register, error shape

error envelope

Wymcp.JsonRpc.error_response/3 The JSON-RPC dialect's object; the tool dialect's isError result is not an error envelope (→ error dialect). The rule its message and data keep is that module's contract section to state.

Avoid: error body, error payload, error map (for the JSON-RPC object)

error type

Wymcp.JsonRpc.error_type/0 The JSON-RPC dialect's atom. The tool dialect's errorType key on a fault diagnostic is a different object — the diagnostic's family value (Wymcp.Tool's containment paragraph names the body's keys), never this atom.

• Avoid: error kind (telemetry's error_kind classifies a tool error's origin — an unrelated vocabulary), error code (for the atom — the code is the integer it maps to)

F

fallthrough

The route that answers any request no other route matches: a verb the mount does not serve with 405 and an Allow: POST header, a POST at a path it does not serve with 404. It runs no wire check and reaches no state. Distinct from a rejection, which is a wire check's answer on a route it guards. Its answer carries the fallthrough mark, which Wymcp.WireCheckInvariantTest reads.

• Avoid: nothing served, nothing-served (for this route), catch-all (for this route), unrouted

fault

A raise, exit or throw in the request process, out of consumer code the framework called or out of wymcp's own — one word for the three kinds a catch can see, whatever a given boundary contains. It is what the fault events ([:wymcp, :tool, :error], [:wymcp, :auth, :error], [:wymcp, :method, :error]) report, each naming the kind under exception and carrying crash_reason — the Logger metadata key, which keeps its library name; the auth boundary contains the raise kind alone today, so its exception is always a struct name. A linked process's exit signal is not a fault: it kills the request process rather than unwinding through it.

• Avoid: crash (for the kind-neutral noun — crash_reason is Logger's key and stays), exception (for the kind-neutral noun — the raise kind alone; the exception key on the fault events and the diagnostic keeps its name and carries the kind), error (the JSON-RPC and tool-dialect objects — → error dialect)

fault containment

Defined in Wymcp.Tool — the containment paragraph of its moduledoc, the one stating what a fault out of run/2 becomes. Avoid: rescue, rescued (for the rule — a rescue is the raise arm's clause alone), fault tolerance, crash safety

H

header annotation

The x-mcp-header key on an input-schema property, naming the Mcp-Param-* header a conforming client mirrors that argument into. Wymcp writes one on every generated schema's action ("Action") and honours any spec-valid one a hand-written schema declares; a schema that breaks a rule is refused at the registration moment, because a conforming client would otherwise exclude the whole tool from its list without telling the server. Distinct from the tool-annotations map annotations/0 returns.

• Avoid: annotation (unqualified), argument annotation, param annotation, x-mcp-header annotation

header binding

The rule that a POST's headers mirror facts in its body — protocol version, method, tool name, and the arguments a tool's header annotations designate — and that a server rejects a missing, disagreeing or malformed mirror with -32020. A mirror is required only where the body value has a header spelling: a tools/call whose name is absent or not a string binds no Mcp-Name and identifies no tool, and an annotated argument whose value its annotation's type cannot spell binds no Mcp-Param-*; the check compares nothing against such a value, so the body's own validator answers a malformed name or action, and a mistyped value under a hand-written annotation reaches the tool, which validates its own arguments. The headers are never authoritative; the body is. Enforced by the header-binding check on modern requests.

• Avoid: header mirroring, header standardization, request metadata (for this concept — that phrase names Wymcp.Context's contents), SEP-2243 (as a name)

header-binding check

The rejecter enforcing header binding on every request, after the protocol fields are proven and before validation: a missing required mirrored header, a value disagreeing with its body field, or a value in invalid form answers HTTP 400 with -32020. Implemented by Wymcp.Plugs.HeaderBinding. Not a wire check: it needs a parsed body.

• Avoid: header check, header-mismatch check, header validation

help

The framework-owned introspection tool — the server's entire introspection surface; defined at its code home, Wymcp.Help (moduledoc).

• Avoid: describe, built-in action, narrowing, topic

help pointer

The copyable help-call suggestion carried under the "help" key of a tool-dialect error payload, telling the LLM which help call explains the surface it just misused. The pointer string is a legal call, never a prose hint; its format lives in one internal builder (Wymcp.Tool).

• Avoid: help link, help hint

host

The application whose HTTP stack a mount sits in — its adapter, endpoint and router pipelines — seen from the wire: what runs ahead of the mount, and what answers whatever escapes it. The same application is the consumer where it uses wymcp's Elixir API; host names its HTTP role, which is what the documented mount constrains (the supported adapter, the unparsed body).

• Avoid: host application, host app, adopter (for the application), consumer (for the HTTP role)

I

icon

An entry in serverInfo's icons list — an image a client may display for the server, authored as a map of snake_case keys that Wymcp.ServerInfo encodes to the MCP Icon wire names. The accepted keys are documented at the :server_info option (Wymcp.Router).

• Avoid: url, media_type (retired earlier key names for src, mime_type)

input-required result

Wymcp.Modern.input_required_result/3

• Avoid: interim result, partial result, input_required (bare, in prose)

instructions

The consumer-authored string guiding how an LLM should use the server's tools, authored as the :instructions router option (Wymcp.Router) and emitted in the server/discover result. Consumer-authored text — governed by the contract at its definition home, the Wymcp.Tool moduledoc.

• Avoid: server instructions, server-level prose

M

message classification

The per-request act of tagging an inbound JSON-RPC message by kind — :request, :notification, or :unknown — from the presence of its discriminating keys, before validation runs, so the rest of the pipeline branches on the kind instead of re-reading body fields. Implemented by Wymcp.Plugs.Classify (its moduledoc carries the classification table).

message validation

Checking a whole inbound JSON-RPC message against the compiled 2026-07-28 protocol schema (JSONRPCMessage), answering a non-conforming message — and a conforming one that is neither a request nor a notification, a client-sent response — with HTTP 400 plus -32600. Implemented by Wymcp.Plugs.Validate over Wymcp.JsonRpc.validate_mcp_request/1. Its sibling one layer down is argument validation, which checks a single tool call's arguments.

• Avoid: envelope validation, schema validation (unqualified)

method containment

Defined in Wymcp.Plugs.Dispatch — the method containment section of its moduledoc, the one stating what a fault past any method becomes.

• Avoid: backstop, dispatch rescue, catch-all, error handler, global rescue

mirrored header

A request header header binding governs — MCP-Protocol-Version, Mcp-Method, Mcp-Name, and the Mcp-Param-* family — whose value is a copy of a body field for intermediaries to read and never the value wymcp acts on.

• Avoid: standard header, standard request header (the spec's phrase for three of the four), bound header

mount

Adding wymcp's HTTP surface to a consumer's application at a route, via Phoenix forward or a bare Plug adapter. The act, whatever the shape mounted; which shape is the blessed one is Wymcp.Router's to say.

• Avoid: add route, wire up (for this act), wiring point

mount module

Wymcp.Router.__using__/1

• Avoid: server module (for this concept), router module, endpoint module

MRTR

Multi round-trip requests — the 2026-07-28 pattern that replaces server-initiated requests: a tools/call (or resources/read, prompts/get) answers resultType: "input_required" carrying the server's inputRequests and an opaque requestState, and the client retries the same call under a new JSON-RPC id, threading its inputResponses and echoing the state byte-exact, until a "complete" result arrives. The spec's own name (SEP-2322); every round is an independent request, which is what lets a server hold no state between them.

• Avoid: multi-round tool results, multi-round, server-request round trip

O

obtaining accessor

An accessor through which a reader obtains an action schema, checking the mandatory pair at the obtaining moment: Wymcp.Tool.Actions.fetch_schema!/3 and Wymcp.Tool.Actions.fetch_schemas!/1, and only those. Wymcp.Tool.Actions.fetch!/1 is deliberately not one — it checks the container's shape only, and no schema field may be read off what it returns.

• Avoid: schema accessor, read accessor, fetch accessor

obtaining moment

The moment a reader obtains an action schema, where its mandatory keys are checked once so downstream field reads need no check of their own; Wymcp.Tool.Actions.fetch_schema!/3 and Wymcp.Tool.Actions.fetch_schemas!/1 are its only sites. The read-side twin of the registration moment: a shape question answered where the value is obtained rather than at each place the value is used.

• Avoid: read-side guard, schema fetch, obtain time

origin check

The wire check rejecting requests whose Origin header is not on the configured allowlist — DNS-rebinding protection. With no allowlist configured every origin is allowed, but a duplicated Origin header is refused either way. Implemented by Wymcp.Plugs.OriginCheck, whose moduledoc carries the full rule.

P

parse step

The inline stage of the POST chain that parses the JSON-RPC body: a rejecter — a refusal it answers is marked and emitted like any rejection — but not a plug and not a wire check, since it runs on POST only, after the origin check and before classification. Which conditions it answers is the rejection table's to state.

• Avoid: parse rescue, body-parse rescue, body parsing (for the stage), parser plug

property name

A key of an action schema's :properties — a string, because it is the JSON object key a caller sends in data. :required, :required_one_of and :defaults refer to properties by it.

• Avoid: field (for a :properties key), parameter

protocol fields

The per-request _meta block: io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities (required on every request), plus optional …/clientInfo and …/logLevel. The spec's own name ("per-request protocol fields"). Enforced by Wymcp.Plugs.ProtocolFields (-32602 / -32022).

• Avoid: modern envelope, _meta envelope

R

re-execution

Defined in Wymcp.Context — the Re-execution section of its moduledoc.

• Avoid: replay, re-run, retry (the client's act, not the tool's property), resumption

registration moment

The moment Wymcp.Router.init/1 builds and validates a mount's configuration — shape questions are answered there, once per build of that configuration, rather than on the path that serves a request. Its timing follows the mount form: in the blessed mount-module form it is the mount module's compile, so a configuration wymcp refuses aborts mix compile and the built configuration is handed back per request as a constant; under a direct forward "/mcp", Wymcp.Router, ... Phoenix defers init/1 to dispatch, so the moment recurs on every request.

• Avoid: init time, boot time

rejecter

The module that sent a rejection, as the rejection mark names it — a wire check, or any other module that records a rejection through the mark-and-emit helper, whether or not it sends through the shared rejection sender.

• Avoid: rejecting plug (a rejecter need not stay a plug), rejecting module, check (for this role — a rejecter that is not a wire check exists)

rejection

An HTTP answer that refuses an inbound message instead of processing it, carrying a status and a diagnostic message in the route's error dialect, the rejection mark naming the rejecter and its reason, and one [:wymcp, :wire, :reject] event carrying the same pair. Which rejecter answers which condition is the rejection table's to state. A tool-level failure is not a rejection — it returns an isError result in the tool dialect — and neither is a method fault, which method containment answers after the message was processed.

rejection id

Wymcp.Response.rejection_id/1

Distinct from the message_id telemetry key, which carries the body's id as the client sent it: the two deliberately differ, and Wymcp.Plugs.Auth states why.

• Avoid: raw body id, request_id (for this concept)

rejection invariant

Defined in Wymcp.Response — the rejection invariant section.

• Avoid: population gate, rejection population test

rejection mark

The record, on the connection, of which rejecter sent a rejection and which reason it named — one map under one key, set on every rejection by the mark-and-emit helper, and read back through Wymcp.Response.rejection/1 as well as by the sweeps.

• Avoid: rejection witness, rejecter tag, rejection flag

rejection reason

Wymcp.Response.rejection_reason/0

• Avoid: reason atom, rejection kind, error type (for this concept — that is the JSON-RPC code's atom)

rejection table

Wymcp.Response.rejection_table/0

• Avoid: rejection registry, rejection population, site list

reserved name

Wymcp.Help.uses_reserved_name?/1

router option

A keyword option declared where wymcp is mounted — the use Wymcp.Router site in the blessed form — and validated into the mount's configuration at the registration moment, which the framework then reads, never anywhere else. What that configuration costs per request follows the mount form: the blessed form stores it in the mount module and hands it back as a constant, while a direct forward "/mcp", Wymcp.Router, ... stores nothing and re-runs Wymcp.Router.init/1 over the literal options on every dispatch. The key set is closed: an unknown key is refused at the registration moment, and so is a documented key given twice. The catalogue, one entry per option, is Wymcp.Router's Options section.

• Avoid: mount option, router config, config option

router-option invariant

Defined in Wymcp.Router — the Options section preamble.

S

served verb

An HTTP verb Wymcp.Router has a route for, declared in its served-verb list and gated against the routes by Wymcp.WireCheckInvariantTest; every other verb reaches the fallthrough.

• Avoid: pinned verb, public verb, public route, wired verb

serverInfo

Wymcp.ServerInfo Spelled :server_info on the Elixir side — the router option and its authoring keys. Distinct from clientInfo, the client's identity in a request's _meta.

serverInfo partial

Wymcp.ServerInfo.encode!/1

• Avoid: wire-shaped partial, identity partial, encoded server_info

singleton header

A request header that may legally carry at most one value. Wymcp's are MCP-Protocol-Version, Mcp-Method, Mcp-Name, any one name of the Mcp-Param-* family, Origin, Content-Type, and Authorization. A duplicate is answered by wymcp policy, not by the MCP spec, which says nothing about repeated headers; one policy is in use — reject, failing closed with a 400 naming the header.

singleton-header check

The wire check that enforces the cardinality of the singleton headers it owns, ahead of the body-bound plugs: MCP-Protocol-Version, Mcp-Method, Mcp-Name and any repeated Mcp-Param-* name reject on a duplicate. Downstream readers of those headers therefore face a two-way present / absent decision. Implemented by Wymcp.Plugs.SingletonHeaders. Origin is not among the headers it owns: the origin check has already validated it, having faced that header before anything else had; Authorization belongs to the consumer's Auth behaviour implementation.

• Avoid: header check

stalled read

A body read the adapter ended short of the body ceiling and before the body's end: no byte of the body arrived for the whole read timeout. Not a body over the ceiling, which the parse step answers with its 413 row; which answer a stalled read meets is the parse step's to state.

• Avoid: read timeout (for the condition — that is the adapter's option and its message), short read (the tuple's shape, not the condition), body timeout, stall (bare)

T

telemetry logger

Wymcp.Telemetry.Logger

• Avoid: default logger, log handler, Wymcp.Logger

totality

Defined in Wymcp.Bound — the Totality section.

• Avoid: crash-safe, never-raises, defensive rendering

V

validation layers

The seven distinct stages that share the word "validate", named apart so the word alone never has to carry the layer. In the order a configuration and then a call meets them: option validation of a router option's shape, in Wymcp.Router.init/1's chain at the registration moment — every router option, under the router-option invariant; the callback-surface check, at a mount module's compile (Wymcp.Tool.validate_callback_surface!/1); action-schema validation of the schemas a tool declares, at a use Wymcp.Tool module's own compile and at a mount module's compile (Wymcp.Tool.Actions.validate!/1) — the tool-module moment stands outside this ordering, since it runs only when no mount module in the same compilation set wires the tool in, and the same stage runs once more, restricted to the mandatory pair, at every obtaining moment; header-annotation validation of a hand-written input_schema/0's header annotations against the spec's constraints, at the registration moment (Wymcp.Tool.Schema.validate_header_annotations!/2); message validation on every inbound message (Wymcp.Plugs.Validate); argument validation of one tools/call's arguments — two hand-written type checks, that action, if present, is a string and data, if present, an object, answered as a distilled error (Wymcp.Methods.ToolsCall.validate_arguments/1); and the dispatch gates, which own vocabulary — unknown argument keys, a missing or unknown action, missing required fields, and unknown keys inside data (Wymcp.Tool.dispatch/3). Wymcp.Help hand-writes its schema and so carries its own counterpart pair — vocabulary through the shared helper, types through its own gate over the keys it declares (Wymcp.Help).

• Avoid: validation stages, the validation pipeline

W

wire check

A plug that may reject a request at the HTTP boundary, before the request reaches the body-bound plugs. Which plugs are wire checks, and the order they run in, is the wire-check invariant's to state.

• Avoid: wire-level guard, guard (for rejecting plugs), gate (for rejecting plugs)

wire-check invariant

Defined in Wymcp.Router — the wire-check invariant section.

wire-in

Supplying a tool module to the framework at its one validated site — a mount's :tools option, validated by Wymcp.Router.init/1 at the registration moment. Distinct from mount, which adds the HTTP surface, not a tool.

• Avoid: registration (for this act — that word belongs to the registration moment), hook-up