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. 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, Wymcp.Bound.echo/1 the echo 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-shape invariant

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

• Avoid: callback-surface invariant (for this rule), return-shape invariant

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

data path

The location of a value inside a call's data, spelled relative to data: a top-level property name bare (status), a nested key dot-joined (items[1].status), an array index in brackets, a key that is not a plain identifier bracket-quoted (spec.elements["my.id"].on), and a key that is not a string written as its inspected term in angle brackets (o[<1>]). A key longer than the bound is cut there and marked …. The empty data path, "", names data itself.

Avoid: property path, key path, instance location (the JSON-RPC dialect's pointer), JSON path

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 none of its own; it honours any spec-valid one a hand-written schema declares, and 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/2 and Wymcp.Tool.Actions.fetch_schemas!/1, and only those.

• 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/2 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

option list

The keyword list of router options a mount hands Wymcp.Router.init/1 — the whole argument, as opposed to any one router option in it.

• Avoid: container, options (for the list as a whole)

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 a properties map in an action schema, at any depth — a string, because it is the JSON object key a caller sends in data or in an object inside it. :required, :required_one_of and :defaults refer by it to the properties of :properties, the top level.

Avoid: field (for a properties key), parameter, nested property name

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

refusal

An answer wymcp gives instead of doing what a request asked, because of what the request carried — in whichever dialect it speaks. A rejection, a dispatch gate's answer and a -32602 invalid-params error are all refusals. A tool's own isError result is not one — it is the consumer's answer, not wymcp's — and neither is a fault.

• Avoid: error answer, failure (for this concept), denial

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, and what the registration moment refuses is the router-option invariant's to state. 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 eight 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 the option list's shape and then each router option's, in Wymcp.Router.init/1's chain at the registration moment — under the router-option invariant; the callback-surface check, at a mount module's compile, and ahead of the callback-shape check at a use Wymcp.Tool module's own compile (Wymcp.Tool.validate_callback_surface!/1); the callback-shape check of what a tool's zero-arity callbacks return, at a use Wymcp.Tool module's own compile and at a mount module's compile (Wymcp.Tool.validate_callback_shape!/1), under the callback-shape invariant, running action-schema validation of the schemas a tool declares (Wymcp.Tool.Actions.validate!/1) as its first part at both moments — 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 action-schema validation 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 properties, and unknown keys at any depth of 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