Glossary

View Source

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

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

Defined in Wymcp.Tool — the action-schema invariant section. 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

C

callback-surface invariant

Wymcp.Tool Avoid: optional-callback contract, callback completeness rule, strict-optional callback, guarded callback

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 verb–check pair must answer either that check's rejection or nothing at all; an exempt pair 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".

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

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

Wymcp.JsonRpc.error_type/0 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)

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 snakecase 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)

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)

M

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

O

obtaining accessor

An accessor through which a runtime reader obtains an action schema, checking the mandatory pair at the obtaining moment: Wymcp.Tool.fetch_action_schema!/3 and Wymcp.Tool.fetch_action_schemas!/1, and only those. Wymcp.Tool.fetch_actions!/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 runtime reader obtains an action schema, where its mandatory keys are checked once so downstream field reads need no check of their own; Wymcp.Tool.fetch_action_schema!/3 and Wymcp.Tool.fetch_action_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, all origins are allowed — existing deployments that never set origin: keep working. 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

Wymcp.Session.push/3 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

Wymcp.Response.rejection_id/1 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

Wymcp.ServerInfo.encode!/1 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

Wymcp.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.validate_actions!/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 runtime 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

Wymcp.Router

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

Grandfathered

Each entry records the term's apparent meaning and where it lives — recorded, not blessed. Grandfathered terms are canonical by default (do not invent synonyms for them) but each awaits a curation pass. Overloaded: marks a term carrying more than one meaning; the cross-cutting flags at the end collect the synonym sets that span entries.

Tools & actions

  • tool — a module implementing the Wymcp.Tool behaviour, exposing named actions to LLM clients; the only MCP primitive wymcp implements. Overloaded: also a string tool name (Hint.tool), a capability flag (capabilities.tools), and a sampling tool definition (CreateMessageRequestParams.tools). (Wymcp.Tool)
  • action-dispatched pattern — the design idiom where one tool name multiplexes many actions. (Wymcp.Tool moduledoc)
  • data — the action-specific parameter sub-object inside a call's arguments. (Wymcp.Tool, Wymcp.Tool.Schema)
  • dispatch — routing a call to its handler. Overloaded: action-level (Wymcp.Tool.dispatch/3 → run_action), method-level (Wymcp.Plugs.Dispatch → Methods.*), and the stock Plug.Router plug(:dispatch). (Wymcp.Tool, Wymcp.Plugs.Dispatch)
  • required — unconditionally required property names, AND-semantics. Overloaded: also the JSON Schema keyword (array) and PromptArgument.required (boolean) in the protocol schema. (Wymcp.Tool)
  • required_one_of — list of property groups; at least one group must be fully present (OR-of-AND), enforced at dispatch and surfaced by the help tool. (Wymcp.Tool)
  • notes / related / examples — optional documentation fields on an action schema; surfaced by the help tool at tool and action level. (Wymcp.Tool)
  • definition — a tool's full MCP wire definition emitted in tools/list: name, description, inputSchema, optional title/annotations/outputSchema. (Wymcp.Tool)
  • input schema (inputSchema on the wire) — the JSON Schema for a tool's arguments, generated from its actions: an action enum whose description carries the action summaries, plus a bare data object. (Wymcp.Tool.Schema)
  • output schema (outputSchema) — optional JSON Schema validating a tool's structured result; enables structuredContent. (Wymcp.Tool, Wymcp.Methods.ToolsCall)
  • structuredContent — the structured response object validated against the output schema, sent alongside content. (Wymcp.Methods.ToolsCall)
  • annotations — optional tool metadata (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). Overloaded: the protocol schema also has Annotations for content metadata (audience, priority, lastModified) — two different definitions. (Wymcp.Tool, priv/schema-2025-11-25.json)
  • title — human-readable display name for a tool or the server. (Wymcp.Tool)
  • isError — flag marking a tools/call result as a tool-originated error, returned as a successful JSON-RPC response with error content so the LLM can self-correct. (Wymcp.Methods.ToolsCall)
  • runtime tools — tools registered on a live session via register_tool/2; win over mount tools on name collision; trigger listChanged. (Wymcp.Session)
  • mount tools — tools the mount module supplies via its :tools option. Antonym pair with runtime tools. (Wymcp.Router, Wymcp.Session) (defaults was promoted on 2026-08-19, action schema on 2026-08-21; both now live in the blessed section.)

Hints & context

  • hint — a follow-up action suggestion (%Wymcp.Hint{}: tool, action, description, optional example) injected into responses via the hints/2 callback. Overloaded: the protocol schema also has ModelHint (sampling model-name preference) and the ToolAnnotations.*Hint behavioral flags. (Wymcp.Hint)
  • hint context — the third element of a 3-tuple run_action return, passed to hints/2; works on both success and error returns. (Wymcp.Tool)
  • context — Overloaded, three meanings: (1) %Wymcp.Context{}, the per-call execution context passed to run_action (session refs, request_id, meta, assigns, result builders); (2) the "context" response key filled by action_context/2; (3) hint context, above. (Wymcp.Context, Wymcp.Tool)
  • action context — per-action dynamic runtime info a tool injects under the "context" response key, via action_context/2. (Wymcp.Tool)
  • assigns — merged per-request conn.assigns + per-session state exposed as ctx.assigns (session wins on collision, internal wymcp keys filtered); tools persist state by returning an assigns-updates map as the third tuple element. (Wymcp.Context, Wymcp.Session)
  • content — the MCP content array of blocks (text, json/structured, image, audio) a tool returns. (Wymcp.Context @type content)
  • result builders — the pure helpers text/1, json/1, image/2, audio/2 producing MCP-compliant content blocks. (Wymcp.Context)

Session & lifecycle

  • session ID (Mcp-Session-Id) — 32-byte URL-safe base64 identifier carried in the header; unknown IDs are rejected with 404 + -32001. (Wymcp.Session, Wymcp.Plugs.Session)
  • session status (:initializing / :ready) — session lifecycle states; notifications/initialized marks ready. Overloaded: the protocol schema's TaskStatus is an unrelated state machine sharing the word. (Wymcp.Session.State)
  • lifecycle gate — the plug check rejecting non-exempt methods while a session is :initializing. (Wymcp.Plugs.Session)
  • idle timeout — configurable inactivity expiry (default 30 min) that terminates a session; every request touches the timer. Distinct from the SSE keepalive. (Wymcp.Session)
  • touch — resetting a session's idle timer on request activity. (Wymcp.Session, Wymcp.Plugs.Session)
  • Server behaviour — the consumer's session-lifecycle hooks: init/2 on ready, terminate/2 on shutdown; deliberately no request hook. Overloaded: "server" also means the MCP server itself, serverInfo, and the "server" in server-initiated requests. (Wymcp.Server)
  • session terminated (-32001, :session_not_found) — the MCP error for an unrecognized session ID, prompting the client to re-initialize. (Wymcp.JsonRpc, Wymcp.Plugs.Session)
  • sessionless fallback (removed) — an earlier implementation's behavior where unknown session IDs fell through to mount tools with _meta.warnings; also called "sessionless mode" and "silent-fallthrough". (session-exempt methods and lifecycle-exempt methods were promoted on 2026-08-28 and now live in the blessed section.)

Protocol & versioning

  • protocol version — a dated MCP spec revision; supported: 2025-11-25 (legacy era) and 2026-07-28 (modern era); the split-endpoint 2024-11-05 is out of scope. Prose also says "revision". (Wymcp.ProtocolVersion)
  • negotiated version — the protocol version pinned on a session at initialize. Appears as protocol_version (state field) and protocolVersion (wire). (Wymcp.Session)
  • counter-proposal — the server answering an unsupported requested version with its own latest in InitializeResult.protocolVersion. (Wymcp.ProtocolVersion, Wymcp.Methods.Initialize)
  • floor — the lowest supported protocol version (2025-11-25 — the floor and the only legacy revision coincide since the pre-1.0 trim). (Wymcp.ProtocolVersion)
  • version gating (removed) — the per-feature supports_*? predicates and strip_* helpers died with the pre-1.0 revision trim; a single-revision legacy era needs no gating. (Wymcp.ProtocolVersion)
  • initialize — the handshake request that negotiates version + capabilities and creates the session. (Wymcp.Methods.Initialize)
  • initialized — notifications/initialized, completing the handshake: transitions the session to ready and runs Server.init/2. (Wymcp.Methods.Initialized)
  • capability — a declared client or server feature (tools, logging, sampling, elicitation, listChanged) exchanged at initialize; server-initiated features are gated on the client's declared capabilities. (Wymcp.Methods.Initialize, Wymcp.Context.check_capability)
  • clientInfo — the client identity from initialize params, stored on the session as client_info. (Wymcp.Methods.Initialize, Wymcp.Session)
  • MCP-Protocol-Version header — HTTP header echoing the negotiated version on post-init requests; enforced on every session (absent header tolerated deliberately). (Wymcp.Plugs.Session) (serverInfo, icon, and instructions were promoted on 2026-08-21 and now live in the blessed section.)

Transport & streaming

  • Streamable HTTP — the MCP transport wymcp implements: POST + optional GET-SSE + DELETE on one endpoint; the older split-endpoint HTTP+SSE transport is deliberately unsupported. The modern era narrows the transport to POST-only; wymcp's GET/DELETE routes are legacy-lane machinery until the legacy drop. (Wymcp.Router)
  • message classification — tagging each inbound JSON-RPC message as :request / :notification / :response / :unknown (conn.assigns.wymcp_message_type) so responses bypass validation and reach deliver_response. (Wymcp.Plugs.Classify)

Server-initiated requests

  • sampling — the server asking the client's LLM for a completion mid-tool-execution (sampling/createMessage via Context.sample/3); blocks until the client replies. (Wymcp.Context)
  • elicitation — the server asking the human user, via the client, for structured input (elicitation/create via Context.elicit); form mode implemented, URL mode deferred. (Wymcp.Context)
  • requestedSchema — the flat JSON Schema an elicitation sends for the client to render as a form. (Wymcp.Context.elicit)
  • accept / decline / cancel — the elicitation response outcomes, carried in its "action" field (see the action overload). (Wymcp.Context.elicit)
  • model preferences — sampling hints and priorities (cost/speed/intelligence priorities, model-name hints). (Wymcp.Context.sample, priv/schema-2025-11-25.json)
  • pending requests — in-flight client→server requests tracked on the session (track_request / complete_request). (Wymcp.Session.State)
  • pending server requests — in-flight server→client requests (sampling/elicitation) awaiting a client reply. (Wymcp.Session.State)

Notifications & utility methods

  • ping — the liveness method; returns an empty result. (Wymcp.Methods.Ping)
  • cancellation — notifications/cancelled, a client aborting a request by requestId + reason; tracked, but no in-flight abort yet. (Wymcp.Methods.Cancelled)
  • progress — notifications/progress updates (progress, total, message) via Context.report_progress, sent only when the request opted in. (Wymcp.Context)
  • progress token — the _meta token opting a request into progress notifications. (Wymcp.Context, priv/schema-2025-11-25.json)
  • _meta — the reserved JSON-RPC metadata property, exposed as Context.meta (spelled meta on the Elixir side); in the modern era it also carries the protocol fields (see protocol fields) and, on results, the io.modelcontextprotocol/serverInfo identity. (Wymcp.Context)
  • logging — server→client notifications/message log entries filtered against the session's log level; the client sets it via logging/setLevel; eight syslog levels debug→emergency. (Wymcp.Session states the ordered level list; Wymcp.Context.log, Wymcp.Methods.LoggingSetLevel)

Auth & validation

  • Noop auth — the default pass-through Auth implementation. (Wymcp.Auth.Noop) (envelope validation and validation layers were promoted on 2026-08-15 and now live in the blessed section as message validation and validation layers.)

Adopted but unimplemented spec surface

Terms the legacy spec overview uses for planned work — present in priv/schema-2025-11-25.json, absent from lib/:

  • resources — application-driven context (resources/list, resources/read); planned. (spec overview §2.2)
  • resource template — URI-template-based resources (resources/templates/list); planned. (spec overview §2.2)
  • prompts — user-controlled templates (prompts/list, prompts/get); planned. (spec overview §2.3)
  • tasks — experimental durable state machines for long-running operations; statuses working / input_required / completed / failed / cancelled (the status overload). (planned; spec overview §4.7)
  • roots — client-declared filesystem boundaries (roots/list). (spec overview §3.3)
  • completion — argument autocompletion (completion/complete). (spec overview §4.5)
  • pagination / cursor — opaque cursor-based paging on list methods (nextCursor). (planned; spec overview §4.6)
  • resource link / embedded resource — resource-referencing content block types. (planned; spec overview §2.1)
  • URL-mode elicitation — elicitation via an external URL (elicitation.url, URLElicitationRequiredError -32042); deferred. (spec overview §3.2)

Cross-cutting flags

Synonym sets and overloads spanning entries — the priority queue for future curation:

  • context ×3 — %Wymcp.Context{} struct vs the "context" response key vs hint context.
  • hint ×3 — follow-up action suggestion vs ModelHint vs ToolAnnotations.*Hint.
  • dispatch ×3 — action-level vs method-level vs Plug.Router internals.
  • server ×5 — MCP server / Wymcp.Server behaviour / server-initiated requests / serverInfo / the :server option's value ("Server module" in raise text).
  • status ×2 — session lifecycle vs task execution state machine.
  • schema ×many — action schema (authoring map) vs JSON Schema maps vs priv/schema-*.json (protocol documents, one per era) vs inputSchema/outputSchema/requestedSchema (wire fields).
  • annotations ×2 — tool behavior hints vs content metadata.
  • name ×many — tool name, action name, serverInfo.name, property name.
  • description ×4 — tool-level description() callback vs action-schema :description vs the JSON Schema property "description" vs serverInfo.description.
  • run ×3 — Methods.*.run, generated Tool.run/2, run_action/3.
  • request_id ×5 — the id a rejection echoes (Wymcp.Response) vs the JSON-RPC envelope builders' parameter (Wymcp.JsonRpc) vs a telemetry/Logger metadata key vs the %Wymcp.Context{} field vs the server-minted id of a server→client sampling or elicitation request (Wymcp.Session, Wymcp.Context). The first and last name ids minted by opposite parties, and they meet at Wymcp.Methods.DeliverResponse.
  • response ×6 — the Wymcp.Response module vs the :response message kind vs the HTTP response vs Wymcp.JsonRpc's response builders vs deliver_response vs Wymcp.Testing's assertion helpers. Three of the six meet inside Wymcp.Response.rejection_id/1.
  • gate ×5 — dispatch gate (blessed) vs the lifecycle gate vs Help's internal vocabulary/type gates vs test-as-gate prose ("map-membership gate", "regression gate") vs revision gating — and "gate" is banned outright for rejecting plugs (see wire check).
  • invariant ×2 — a named drift rule with a prose home (action-schema, callback-surface, router-option, wire-check) vs era-invariant, same-on-both-eras.
  • vocabulary ×2 — a closed key/name set (action-schema keys, arguments, router options) vs a return-value set (the reply, ack, and error vocabularies; telemetry's error_kind).
  • negotiated version ≈ protocol version ≈ revision ≈ protocolVersion — one concept, four spellings across resolver, state, prose, and wire.
  • session assigns ≈ per-session state ≈ per-session assigns — one concept in prose.
  • camelCase ↔ snake_case — wire vs Elixir spellings of the same fields (inputSchema/input_schema, serverInfo/server_info, _meta/meta, Mcp-Session-Id/session_id).