# Noizu MCP v0.1.6 - Table of Contents

> Model Context Protocol (MCP) for Elixir — server and client, full spec surface
(tools, resources, prompts, sampling, elicitation, roots) over stdio and
Streamable HTTP transports. Behaviour-driven core with an optional macro DSL.

## Pages

- [Noizu MCP](readme.md)
- [Changelog](changelog.md)

- Guides
  - [Getting Started](getting_started.md)
  - [Tools &amp; Schemas](tools.md)
  - [Toolkits, Categories &amp; Hidden Tools](toolkits_and_discovery.md)
  - [Resources, Templates &amp; Prompts](resources_and_prompts.md)
  - [The Handler Context (Noizu.MCP.Ctx)](handler_context.md)
  - [Consuming Servers (Client)](client.md)
  - [Streamable HTTP Deployment](streamable_http.md)
  - [stdio Deployment](stdio.md)
  - [Authentication (OAuth 2.1)](authentication.md)
  - [Authorization Server (OAuth 2.1 facade)](authorization_server.md)
  - [MCP client compatibility](mcp_client_compatibility.md)
  - [Testing Your Server](testing.md)
  - [Inspector (mix mcp.client)](inspector.md)

- Cheatsheets
  - [Noizu MCP Cheatsheet](mcp.md)

## Modules

- [Noizu.MCP](Noizu.MCP.md): Model Context Protocol (MCP) for Elixir — server and client.
- [Noizu.MCP.Description](Noizu.MCP.Description.md): A tailored description: one string chosen per render context, with gap-fill
interpolation for verbosity levels that no variant covers and — for weak
harnesses/models — per-runner/model overrides (spec §3).
- [Noizu.MCP.Eval](Noizu.MCP.Eval.md): Inline `@eval` annotations for description tuning (spec §4).
- [Noizu.MCP.Eval.Harness](Noizu.MCP.Eval.Harness.md): Core of the `mix noizu.mcp.eval` description-tuning harness (spec §4).
- [Noizu.MCP.Eval.Judge](Noizu.MCP.Eval.Judge.md): Behaviour for grading a single rubric criterion against a transcript (spec §4).
- [Noizu.MCP.Eval.Judge.Stub](Noizu.MCP.Eval.Judge.Stub.md): Deterministic no-LLM judge for tests and CI (spec §4).
- [Noizu.MCP.Eval.Runner](Noizu.MCP.Eval.Runner.md): Behaviour for executing an eval prompt against a target (spec §4).
- [Noizu.MCP.Eval.Runner.Stub](Noizu.MCP.Eval.Runner.Stub.md): Deterministic no-LLM runner for tests and CI (spec §4).
- [Noizu.MCP.Eval.Spec](Noizu.MCP.Eval.Spec.md): A compiled eval specification attached to a tool (spec §4).
- [Noizu.MCP.RenderCtx](Noizu.MCP.RenderCtx.md): Render context threaded through every description render site.

- Server
  - [Noizu.MCP.Server](Noizu.MCP.Server.md): Define an MCP server.
  - [Noizu.MCP.Server.EventStore](Noizu.MCP.Server.EventStore.md): Buffer for Streamable HTTP messages that had no live stream to deliver to,
enabling SSE resumability via `Last-Event-ID`.
  - [Noizu.MCP.Server.Features.Prompts](Noizu.MCP.Server.Features.Prompts.md): Prompts feature plumbing: the helpers behind the generated
`handle_list_prompts/2` and `handle_get_prompt/3` defaults.
  - [Noizu.MCP.Server.Features.Resources](Noizu.MCP.Server.Features.Resources.md): Resources feature plumbing: the helpers behind the generated
`handle_list_resources/2`, `handle_list_resource_templates/2`,
`handle_read_resource/2`, and `handle_subscribe/2` defaults.
  - [Noizu.MCP.Server.Features.Tools](Noizu.MCP.Server.Features.Tools.md): Tools feature plumbing: the helpers behind the generated
`handle_list_tools/2` and `handle_call_tool/3` defaults.
  - [Noizu.MCP.Server.Prompt](Noizu.MCP.Server.Prompt.md): Define an MCP prompt as a module.
  - [Noizu.MCP.Server.Resource](Noizu.MCP.Server.Resource.md): Define an MCP resource as a module.
  - [Noizu.MCP.Server.ResourceTemplate](Noizu.MCP.Server.ResourceTemplate.md): Define an MCP resource template (RFC 6570 `{var}` URIs) as a module.
  - [Noizu.MCP.Server.Session](Noizu.MCP.Server.Session.md): One MCP session: a GenServer owning the protocol state (`Noizu.MCP.Peer`)
for a single connected client.
  - [Noizu.MCP.Server.Supervisor](Noizu.MCP.Server.Supervisor.md): Supervision tree for one logical MCP server: a session registry, a dynamic
supervisor for per-client sessions, a task supervisor for handler execution,
and (when `transport: :stdio`) the stdio transport with its single implicit
session.
  - [Noizu.MCP.Server.Tool](Noizu.MCP.Server.Tool.md): Define an MCP tool as a module.
  - [Noizu.MCP.Server.Tool.Spec](Noizu.MCP.Server.Tool.Spec.md): Normalized runtime descriptor for one registered tool.
  - [Noizu.MCP.Server.Toolkit](Noizu.MCP.Server.Toolkit.md): Define several MCP tools in one module by annotating functions with `@mcp`.
  - [Noizu.MCP.Server.Tools.Catalog](Noizu.MCP.Server.Tools.Catalog.md): Built-in catalog discovery tool.

- Client
  - [Noizu.MCP.Client](Noizu.MCP.Client.md): MCP client: connect to an MCP server over a transport and call its tools,
resources, and prompts.
  - [Noizu.MCP.Client.Handler](Noizu.MCP.Client.Handler.md): Callbacks for server-initiated MCP traffic on the client side.
  - [Noizu.MCP.Client.Telemetry](Noizu.MCP.Client.Telemetry.md): Telemetry events emitted by `Noizu.MCP.Client`.

- Handler Context
  - [Noizu.MCP.Ctx](Noizu.MCP.Ctx.md): Per-request handler context.

- Types
  - [Noizu.MCP.Types.Content](Noizu.MCP.Types.Content.md): An MCP content block: text, image, audio, resource link, or embedded resource.
  - [Noizu.MCP.Types.Implementation](Noizu.MCP.Types.Implementation.md): Identity of an MCP client or server (`clientInfo` / `serverInfo`).
  - [Noizu.MCP.Types.Prompt](Noizu.MCP.Types.Prompt.md): An MCP prompt definition as advertised by `prompts/list`.
  - [Noizu.MCP.Types.Prompt.Argument](Noizu.MCP.Types.Prompt.Argument.md): A prompt argument (protocol-level string key/value).
  - [Noizu.MCP.Types.PromptMessage](Noizu.MCP.Types.PromptMessage.md): A message in a `prompts/get` result.
  - [Noizu.MCP.Types.Resource](Noizu.MCP.Types.Resource.md): An MCP resource definition as advertised by `resources/list`.
  - [Noizu.MCP.Types.ResourceContents](Noizu.MCP.Types.ResourceContents.md): The contents of a read resource. Text resources carry `:text`; binary
resources carry `:blob` (raw binary, base64-encoded on the wire).

  - [Noizu.MCP.Types.ResourceTemplate](Noizu.MCP.Types.ResourceTemplate.md): An MCP resource template (`resources/templates/list`), RFC 6570 URI template.
  - [Noizu.MCP.Types.Root](Noizu.MCP.Types.Root.md): A filesystem root exposed by an MCP client (`roots/list`).
  - [Noizu.MCP.Types.Tool](Noizu.MCP.Types.Tool.md): An MCP tool definition as advertised by `tools/list`.
  - [Noizu.MCP.Types.ToolResult](Noizu.MCP.Types.ToolResult.md): The result of a `tools/call` — content blocks, optional structured content,
and the `isError` execution-error flag.

- Transports
  - [Noizu.MCP.Transport](Noizu.MCP.Transport.md): Transport behaviours.
  - [Noizu.MCP.Transport.Client](Noizu.MCP.Transport.Client.md): Client-side transport behaviour. See `Noizu.MCP.Transport`.
  - [Noizu.MCP.Transport.SSE](Noizu.MCP.Transport.SSE.md): Minimal Server-Sent Events codec used by the Streamable HTTP transport.
Encoder for the server side, incremental parser for the client side.

  - [Noizu.MCP.Transport.SSE.Event](Noizu.MCP.Transport.SSE.Event.md): A parsed server-sent event.
  - [Noizu.MCP.Transport.Server](Noizu.MCP.Transport.Server.md): Server-side transport sink behaviour. See `Noizu.MCP.Transport`.
  - [Noizu.MCP.Transport.Stdio](Noizu.MCP.Transport.Stdio.md): stdio server transport: newline-delimited JSON-RPC on stdin/stdout.
  - [Noizu.MCP.Transport.Stdio.Client](Noizu.MCP.Transport.Stdio.Client.md): stdio client transport: spawns an MCP server as a subprocess and speaks
newline-delimited JSON-RPC over its stdin/stdout.
  - [Noizu.MCP.Transport.StreamableHTTP.Client](Noizu.MCP.Transport.StreamableHTTP.Client.md): Streamable HTTP client transport (Req-based).
  - [Noizu.MCP.Transport.StreamableHTTP.Plug](Noizu.MCP.Transport.StreamableHTTP.Plug.md): Streamable HTTP server transport (MCP 2025-11-25): a single MCP endpoint
handling POST/GET/DELETE, mountable in Phoenix or any Plug stack
  - [Noizu.MCP.Transport.Test](Noizu.MCP.Transport.Test.md): In-memory transport for tests.
  - [Noizu.MCP.Transport.Test.Client](Noizu.MCP.Transport.Test.Client.md): In-memory client transport: connects a `Noizu.MCP.Client` to a
`Noizu.MCP.Server` running in the same VM, preserving the full
encode/decode boundary.

- Inspector
  - [Noizu.MCP.Inspector](Noizu.MCP.Inspector.md): Interactive HTML inspector for MCP servers — the engine behind
`mix mcp.client`. Starts a localhost-only Bandit endpoint serving a
single-page UI plus a JSON/SSE bridge to `Noizu.MCP.Client` sessions.
  - [Noizu.MCP.Inspector.Handler](Noizu.MCP.Inspector.Handler.md): `Noizu.MCP.Client.Handler` for the inspector: server-initiated sampling and
elicitation requests are parked in the inspector session and surfaced in the
browser (Pending tab), blocking until a human answers. Roots come from the
session's editable roots list.

  - [Noizu.MCP.Inspector.Plug](Noizu.MCP.Inspector.Plug.md): HTTP surface of the inspector: serves the single-page UI from
`priv/inspector/` and a JSON + SSE bridge to inspector sessions.
  - [Noizu.MCP.Inspector.Session](Noizu.MCP.Inspector.Session.md): One inspector session: owns a `Noizu.MCP.Client` connected to the target
server (through `Noizu.MCP.Inspector.TapTransport`), buffers an event stream
for the browser (raw frames, notifications, progress, async call results,
pending sampling/elicitation requests), and parks server-initiated requests
until a human answers them in the UI.
  - [Noizu.MCP.Inspector.TapTransport](Noizu.MCP.Inspector.TapTransport.md): Transport decorator used by the inspector: wraps a real client transport and
mirrors every wire frame to the inspector session as
`{:inspector_frame, :tx | :rx, binary}` so the UI can show raw JSON-RPC
history without touching `Noizu.MCP.Client`.

- Authorization Server
  - [Noizu.MCP.Auth.Server](Noizu.MCP.Auth.Server.md): OAuth 2.1 authorization-server facade for MCP hosts.
  - [Noizu.MCP.Auth.Server.ApiKeyTokenPlug](Noizu.MCP.Auth.Server.ApiKeyTokenPlug.md): Trade a host API key for a short-lived, audience-bound access token —
`POST /api/mcp/token`.
  - [Noizu.MCP.Auth.Server.AuthorizePlug](Noizu.MCP.Auth.Server.AuthorizePlug.md): The authorization endpoint (RFC 6749 §4.1.1, OAuth 2.1) and the consent
decision that goes with it.
  - [Noizu.MCP.Auth.Server.CIMD](Noizu.MCP.Auth.Server.CIMD.md): Client-ID Metadata Documents: a `client_id` that is itself an https URL serving
the client's own metadata.
  - [Noizu.MCP.Auth.Server.CIMD.ReqFetcher](Noizu.MCP.Auth.Server.CIMD.ReqFetcher.md): Default CIMD fetcher, over `:req`. Used automatically when `:req` is in your
deps; pass `cimd: [fetcher: ...]` to substitute anything else.
  - [Noizu.MCP.Auth.Server.Client](Noizu.MCP.Auth.Server.Client.md): An OAuth client of this authorization server, and the validation that admits
one.
  - [Noizu.MCP.Auth.Server.Config](Noizu.MCP.Auth.Server.Config.md): Validated configuration for the authorization-server facade — the struct every
plug in `Noizu.MCP.Auth.Server` receives.
  - [Noizu.MCP.Auth.Server.Consent](Noizu.MCP.Auth.Server.Consent.md): Consent policy and the default consent screen.
  - [Noizu.MCP.Auth.Server.Errors](Noizu.MCP.Auth.Server.Errors.md): OAuth error codes and rendering (RFC 6749 §4.1.2.1/§5.2, RFC 7591 §3.2.2,
RFC 8707 §2, RFC 6750 §3.1).
  - [Noizu.MCP.Auth.Server.JWKSPlug](Noizu.MCP.Auth.Server.JWKSPlug.md): The JWKS document — `GET /oauth/jwks`. **RS256 mode only.**
  - [Noizu.MCP.Auth.Server.MetadataPlug](Noizu.MCP.Auth.Server.MetadataPlug.md): RFC 8414 authorization-server metadata, aliased at
`/.well-known/openid-configuration`.
  - [Noizu.MCP.Auth.Server.PKCE](Noizu.MCP.Auth.Server.PKCE.md): PKCE (RFC 7636), **S256 only**.
  - [Noizu.MCP.Auth.Server.Params](Noizu.MCP.Auth.Server.Params.md): Parameter extraction for the OAuth endpoints.
  - [Noizu.MCP.Auth.Server.PlugSupport](Noizu.MCP.Auth.Server.PlugSupport.md): Shared plumbing for the authorization-server endpoints: parameter reading,
client authentication, uniform error rendering, `cache-control: no-store`,
CORS, and the rate-limit hook.
  - [Noizu.MCP.Auth.Server.RedirectURI](Noizu.MCP.Auth.Server.RedirectURI.md): Redirect-URI validation and matching (RFC 6749 §3.1.2, RFC 8252, OAuth 2.1).
  - [Noizu.MCP.Auth.Server.RegistrationPlug](Noizu.MCP.Auth.Server.RegistrationPlug.md): RFC 7591 dynamic client registration — `POST /oauth/register`.
  - [Noizu.MCP.Auth.Server.RevokePlug](Noizu.MCP.Auth.Server.RevokePlug.md): Token revocation (RFC 7009) — `POST /oauth/revoke`.
  - [Noizu.MCP.Auth.Server.Router](Noizu.MCP.Auth.Server.Router.md): One forward for the whole authorization server.
  - [Noizu.MCP.Auth.Server.SSRF](Noizu.MCP.Auth.Server.SSRF.md): Guards for the one place the authorization server fetches a URL a *client*
chose: the CIMD (client-id metadata document) fetch, where `client_id` is
itself an `https` URL the server dereferences.
  - [Noizu.MCP.Auth.Server.Secret](Noizu.MCP.Auth.Server.Secret.md): Secret generation, hashing and constant-time comparison for the
authorization-server facade.
  - [Noizu.MCP.Auth.Server.Store](Noizu.MCP.Auth.Server.Store.md): Persistence contract for the authorization-server facade.
  - [Noizu.MCP.Auth.Server.Store.AccessToken](Noizu.MCP.Auth.Server.Store.AccessToken.md): An issued access token, tracked **only** when `track_access_tokens: true`.
`jti` is raw on the way in; the adapter stores its hash. Tracking buys
immediate revocation; not tracking means a token is good until it expires,
which is why the TTL ceiling is 15 minutes.

  - [Noizu.MCP.Auth.Server.Store.AuthorizationCode](Noizu.MCP.Auth.Server.Store.AuthorizationCode.md): A pending authorization code. `code` is raw on the way in and is **never**
stored; the adapter persists `Secret.token_hash(code)`.
  - [Noizu.MCP.Auth.Server.Store.Consent](Noizu.MCP.Auth.Server.Store.Consent.md): A recorded grant of scope by a subject to a client. Unique on
`{subject, client_id}`; `scope` is the union granted so far, so a request for
a scope outside it re-prompts (the spec's confused-deputy requirement).

  - [Noizu.MCP.Auth.Server.Store.ETS](Noizu.MCP.Auth.Server.Store.ETS.md): In-memory `Noizu.MCP.Auth.Server.Store` adapter.
  - [Noizu.MCP.Auth.Server.Store.Ecto](Noizu.MCP.Auth.Server.Store.Ecto.md): Postgres `Noizu.MCP.Auth.Server.Store` adapter, in **raw SQL**.
  - [Noizu.MCP.Auth.Server.Store.RefreshToken](Noizu.MCP.Auth.Server.Store.RefreshToken.md): A refresh token. `token` is raw on the way in and never stored.
  - [Noizu.MCP.Auth.Server.TokenPlug](Noizu.MCP.Auth.Server.TokenPlug.md): The token endpoint — `POST /oauth/token`. Two grants:
`authorization_code` and `refresh_token`.
  - [Noizu.MCP.Auth.Server.Tokens](Noizu.MCP.Auth.Server.Tokens.md): Minting: access tokens (signed JWTs), refresh tokens and authorization codes
(opaque random, hashed at rest).
  - [Noizu.MCP.Auth.Server.Upstream](Noizu.MCP.Auth.Server.Upstream.md): How the authorization server authenticates the *human*.
  - [Noizu.MCP.Auth.Server.Upstream.HostSession](Noizu.MCP.Auth.Server.Upstream.HostSession.md): The default `Noizu.MCP.Auth.Server.Upstream`: reuse the host application's
**existing** login.
  - [Noizu.MCP.Auth.Server.Upstream.OIDC](Noizu.MCP.Auth.Server.Upstream.OIDC.md): Optional fallback `Noizu.MCP.Auth.Server.Upstream`: run an OIDC
authorization-code round trip against the IdP ourselves.

- Authorization
  - [Noizu.MCP.Auth.ApiKeyVerifier](Noizu.MCP.Auth.ApiKeyVerifier.md): Accepts a raw API key presented as a bearer token.
  - [Noizu.MCP.Auth.ChainVerifier](Noizu.MCP.Auth.ChainVerifier.md): Tries several verifiers in order and takes the first success.
  - [Noizu.MCP.Auth.ClientStrategy](Noizu.MCP.Auth.ClientStrategy.md): Client-side authorization strategy for the Streamable HTTP transport.
  - [Noizu.MCP.Auth.CompoundJWTVerifier](Noizu.MCP.Auth.CompoundJWTVerifier.md): Built-in compound JWT verifier for dual-auth MCP tokens.
  - [Noizu.MCP.Auth.JWTVerifier](Noizu.MCP.Auth.JWTVerifier.md): Audience-checking JWT verifier for an MCP mount.
  - [Noizu.MCP.Auth.OAuth](Noizu.MCP.Auth.OAuth.md): OAuth 2.1 client strategy for MCP Streamable HTTP: discovery (RFC 9728
protected-resource metadata → RFC 8414 / OIDC authorization-server
metadata), PKCE S256 authorization-code flow with the RFC 8707 `resource`
parameter, token refresh, and `insufficient_scope` step-up.
  - [Noizu.MCP.Auth.ProtectedResourceMetadataPlug](Noizu.MCP.Auth.ProtectedResourceMetadataPlug.md): Serves the RFC 9728 protected-resource metadata document MCP clients use
to discover your authorization server
  - [Noizu.MCP.Auth.Resource](Noizu.MCP.Auth.Resource.md): Canonical resource identifiers (RFC 8707 / RFC 9728).
  - [Noizu.MCP.Auth.Static](Noizu.MCP.Auth.Static.md): Fixed bearer-token auth strategy: `{Noizu.MCP.Auth.Static, token: "..."}`.
A 401 is terminal — there is nothing to refresh.

  - [Noizu.MCP.Auth.TokenVerifier](Noizu.MCP.Auth.TokenVerifier.md): Server-side bearer-token verification for the Streamable HTTP transport.
  - [Noizu.MCP.Auth.WWWAuthenticate](Noizu.MCP.Auth.WWWAuthenticate.md): Parse and format `WWW-Authenticate` challenges (RFC 9110 §11.6.1), as used
by the MCP authorization spec to point clients at protected-resource
metadata and signal `insufficient_scope` step-up.

- Testing
  - [Noizu.MCP.Test](Noizu.MCP.Test.md): Test helpers for exercising `Noizu.MCP.Server` modules over an in-memory
transport — no sockets, `async: true` safe.

- Protocol
  - [Noizu.MCP.Error](Noizu.MCP.Error.md): Protocol-level MCP / JSON-RPC error.
  - [Noizu.MCP.JsonRpc](Noizu.MCP.JsonRpc.md): JSON-RPC 2.0 framing for MCP.
  - [Noizu.MCP.JsonRpc.ErrorResponse](Noizu.MCP.JsonRpc.ErrorResponse.md): A JSON-RPC error response.
  - [Noizu.MCP.JsonRpc.Notification](Noizu.MCP.JsonRpc.Notification.md): A JSON-RPC notification (no response expected).
  - [Noizu.MCP.JsonRpc.Request](Noizu.MCP.JsonRpc.Request.md): An inbound or outbound JSON-RPC request (expects a response).
  - [Noizu.MCP.JsonRpc.Response](Noizu.MCP.JsonRpc.Response.md): A successful JSON-RPC response.
  - [Noizu.MCP.Peer](Noizu.MCP.Peer.md): Sans-IO MCP session core, shared by server sessions and client connections.
  - [Noizu.MCP.Protocol.Methods](Noizu.MCP.Protocol.Methods.md): Compile-time registry of MCP methods: kind (request/notification) and
direction (client→server, server→client, or both).

  - [Noizu.MCP.Protocol.Version](Noizu.MCP.Protocol.Version.md): Protocol version negotiation.
  - [Noizu.MCP.Schema](Noizu.MCP.Schema.md): JSON Schema validation (2020-12, MCP's default dialect) backed by `JSV`.
  - [Noizu.MCP.UriTemplate](Noizu.MCP.UriTemplate.md): Minimal RFC 6570 (level 1) URI template support: simple `{var}` expressions.

## Mix Tasks

- [mix mcp.client](Mix.Tasks.Mcp.Client.md): Start `Noizu.MCP.Inspector` — a rich interactive HTML client for exploring
and exercising MCP servers (tools, resources, prompts, sampling,
elicitation, raw JSON-RPC history) — and open it in your browser.
- [mix noizu.mcp.eval](Mix.Tasks.Noizu.Mcp.Eval.md): Run the description-tuning eval harness (spec §4) against a `Noizu.MCP.Server`.

