Glossary
View SourceCanonical 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
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
- Avoid: action definition ("definition" names the tool-level wire object), tool schema
action-schema invariant
- 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
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
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. The conformance maps speak the same word at
map altitude — an era-varying cell is one requirement's answer on one
era, where the eras differ.
- Avoid: verb–check pair
check-exempt verb
An HTTP verb whose route Wymcp.Router deliberately serves without one
named wire check — a CORS preflight is exempt from the auth check, because
it carries no Authorization header, while the origin and singleton-header
checks still run on it. The exemption is always per verb and check, never
blanket. There are none: the record is Wymcp.WireCheckInvariantTest's
@check_exempt_verbs, empty, each future entry naming its check and the
reason. Every other cell must answer either that check's rejection or
nothing at all; 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
- Avoid: tool spec, descriptor, tool entry, listing
dirty tool list
Defined at its code home: the Wymcp.Session moduledoc, section "Tool list
notifications".
- Avoid: stale tool list, pending notification
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: a one-line message plus an
errors list of %{at, problems} entries).
- Avoid: normalized error, full error tree (for this wire shape)
E
era
The protocol's two generations, as the 2026-07-28 spec defines them: the
modern era (2026-07-28 and later — per-request _meta metadata,
stateless) and the legacy era (2025-11-25 and earlier — the initialize
handshake and sessions). A server supporting both is dual-era. The
split-endpoint 2024-11-05 revision predates wymcp's support and belongs to
neither era's serving surface.
- Avoid: sessionless / session era / initialize era (for the legacy era), "legacy" (for 2024-11-05)
era classification
The per-request act of deciding which lane serves an inbound message: a
request carrying the modern _meta protocol fields classifies modern; an
initialize request classifies legacy. Kin to message classification —
an early tag the rest of the pipeline reads. Implemented by
Wymcp.Plugs.Era (its moduledoc carries the classification table).
- Avoid: era dispatch, era detection, era selection
error dialect
The error-body convention an HTTP answer speaks. Wymcp has three
structured dialects: the JSON-RPC dialect (the enveloped error object
POST answers), the plain-JSON dialect (the flat %{error: "…"} object
the GET/DELETE route errors answer), and the tool dialect (the isError
tool-result payload). Each route's errors speak one dialect.
- Avoid: register, error register, error shape
error type
- Avoid: error kind (telemetry's
error_kindclassifies a tool error's origin — an unrelated vocabulary), error code (for the atom — the code is the integer it maps to)
event ID
The monotonic per-event SSE identifier (evt-N), carried on the wire as
the SSE id field and read back from the Last-Event-ID request header.
A reconnect resumes the counter; replay of missed events is not
implemented.
H
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
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)
instructions
The consumer-authored string guiding how an LLM should use the server's
tools, authored as the :instructions router option (Wymcp.Router).
The legacy lane emits it in the initialize result, the modern lane 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
K
keepalive
The periodic SSE comment (default 15 s) that keeps a stream's connection from being idle-disconnected by proxies. Distinct from the session idle timeout.
L
lane
An era's serving path through wymcp — the plugs, methods, and machinery
that serve exactly one era. Wymcp has two: the modern lane (stateless,
per-request) and the legacy lane (sessions and streams). The lanes meet at
tool dispatch; the legacy lane is the subtree the eventual legacy drop
deletes. Tests exercising the legacy lane carry @tag era: :legacy
(@moduletag/@describetag where a whole file or describe is
legacy-lane); an untagged test is not obviously legacy, not certified
to survive — the tag is an advisory marker, and the drop confirms usage
before deleting. Era-neutral rules pinned on legacy-lane fixtures are
ported to the modern lane at the drop, not deleted — their doc tags
carry a port note. Code that exists only because the legacy era does is
legacy-only — a wider set than this term names, and marked in place.
- Avoid: leg (for this concept), stack, side
legacy-only
A property of a code site: it exists only because the legacy era does, so
it goes at the legacy decommission. Wider than the legacy lane — a
legacy-only site can sit inside an era-neutral module, as
%Wymcp.Context{}'s era field and Wymcp.Telemetry's era paragraph do.
Such a site is marked in place with the token legacy-only, matched
case-insensitively, so the drop is one sweep rather than archaeology: a
whole module carries an ExDoc admonition opening its @moduledoc
(> ### Legacy-only {: .warning}), and a single site carries the token
and its reason — in a # comment at a code site, in the paragraph
documenting the thing at a doc site. Advisory, exactly as the @tag era: :legacy convention above is: untagged means not obviously legacy, not
certified to survive, and the drop confirms usage before deleting. The
token is the whole mechanism — no registry, no census test.
- Avoid: deprecated (legacy-lane code is fully supported until the drop), doomed, legacy-lane (for this property — that names a serving path)
lifecycle-exempt methods
Defined in Wymcp.Plugs.Session — the Exemptions subsection of its
moduledoc.
list changed
The listChanged capability declared at initialize and the
notifications/tools/list_changed notification it promises. Wymcp declares
and sends it for tools only; the resources and prompts variants are
unimplemented.
- Avoid: list-changed hint, hint (for this notification)
M
message classification
The per-request act of tagging an inbound JSON-RPC message by kind —
:request, :notification, :response, or :unknown — from the
presence of its discriminating keys, before validation runs, so that a
client's answer to a server-initiated request bypasses validation and
reaches delivery. Kin to era classification — an early tag the rest of
the pipeline reads. Implemented by Wymcp.Plugs.Classify (its moduledoc
carries the classification table).
message validation
Checking a whole inbound JSON-RPC message against its era's compiled MCP
protocol schema (JSONRPCMessage), answering a non-conforming message with
HTTP 400 plus -32600. Implemented by Wymcp.Plugs.Validate over
Wymcp.JsonRpc.validate_mcp_request/2. Its sibling one layer down is
argument validation, which checks a single tool call's arguments.
- Avoid: envelope validation, schema validation (unqualified)
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
- Avoid: server module (for this concept), router module, endpoint module
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
priming event
The initial empty SSE event a new stream sends, giving the client an event ID for reconnection.
protocol fields
The modern era's per-request _meta block: io.modelcontextprotocol/protocolVersion
and io.modelcontextprotocol/clientCapabilities (required on every modern
request), plus optional …/clientInfo and …/logLevel. The spec's own
name ("per-request protocol fields"); their presence is what classifies a
request modern. Enforced by Wymcp.Plugs.ProtocolFields
(-32602 / -32022).
- Avoid: modern envelope, _meta envelope, era envelope
push
- Avoid: push event, push_event
push ack
The stream loop's answer to one push — :ok for a completed chunk write,
an error tuple otherwise. Delivered to whoever awaits the push: the pusher
directly on a plain push, the session on a server-request round trip's
push leg.
- Avoid: push reply, push result
R
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 in the lanes that serve 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. Distinct from runtime
registration, which adds a tool to one live session
(Wymcp.Session.register_tool/2).
- Avoid: init time, boot time
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. A
wire check sends one, and so do Wymcp.Plugs.Era,
Wymcp.Plugs.ProtocolFields, Wymcp.Plugs.Session, and
Wymcp.Plugs.Validate; a tool-level failure is not one — it returns an
isError result in the tool dialect.
rejection id
- Avoid: raw body id, request_id (for this concept)
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
serverInfo
Wymcp.ServerInfo
Spelled :server_info on the Elixir side — the router option and its
authoring keys. Distinct from clientInfo, the client's identity from
initialize.
serverInfo partial
- Avoid: wire-shaped partial, identity partial, encoded server_info
server-request round trip
The blocking round trip a server-initiated request (sampling, elicitation)
makes: the session pushes the request over SSE, holds the calling process,
and unblocks it when the client POSTs the response back
(await_client_response → deliver_response).
- Avoid: deferred reply
session
session-exempt methods
Defined in Wymcp.Plugs.Session — the Exemptions subsection of its
moduledoc.
session opts
Wymcp.Testing.build_session_opts/1
- Avoid: session-init map
singleton header
A request header that may legally carry at most one value. Wymcp's are
Mcp-Session-Id, MCP-Protocol-Version, Last-Event-ID, Origin, and
Authorization. A duplicate is answered by wymcp policy, not by the MCP
spec, which says nothing about repeated headers; two policies are in use —
reject, failing closed with a 400 naming the header, and degrade,
proceeding without the header's value and logging a warning.
singleton-header check
The wire check that enforces the cardinality of the singleton headers it
owns, before the request touches any session state: Mcp-Session-Id and
MCP-Protocol-Version reject on a duplicate, Last-Event-ID degrades.
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 runs first, so nothing has
validated that header by the time it reads it; Authorization belongs to
the consumer's Auth behaviour implementation.
- Avoid: header check
stream
Wymcp.Transport.Stream
Avoid: StreamManager, stream manager
stream-answered push
The push design in which the stream loop answers the pusher itself: the session hands the message and the caller's reply reference to the loop and never blocks on a socket write.
- Avoid: forwarded ack
V
validation layers
The six 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 and at runtime registration
(Wymcp.Tool.validate_callback_surface!/1); action-schema validation
of the schemas a tool declares, at a use Wymcp.Tool module's own compile,
at a mount module's compile, and at runtime registration
(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;
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 touches any session state. Wymcp has three: the origin check, the auth check, and the singleton-header check, run in that order.
- 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 one of the two validated
sites — a mount's :tools option, validated by Wymcp.Router.init/1 at
the registration moment, or Wymcp.Session.register_tool/2 at runtime
registration. The umbrella over the mount-tools and runtime-tools paths;
distinct from mount, which adds the HTTP surface, not a tool.
- Avoid: registration (for the umbrella act — that word belongs to the runtime path and the registration moment), hook-up