fastest_mcp

# Changelog

## 0.2.0 - 2026-08-12

This is a breaking protocol and lifecycle release. Applications upgrading from
0.1.x should review the migration notes below before deploying.

### MCP protocol and transport

- make MCP `2025-11-25` the sole negotiated protocol version; server metadata
  can add experimental capabilities but can no longer override the protocol
  version or standard capability shape
- accept MCP traffic only at the configured endpoint, `/mcp` by default, and
  remove the `/health`, trailing-slash redirect, and method-specific HTTP routes
  such as `/mcp/tools`, `/mcp/resources/read`, and `/mcp/tasks/*`; applications
  can provide their own health or non-MCP routes in the surrounding Plug router
- require JSON-RPC 2.0 envelopes and exactly one request, notification, or
  response per HTTP POST or stdio message; JSON-RPC batch arrays are no longer
  accepted
- require streamable HTTP POST requests to use `Content-Type:
  application/json` and advertise both `application/json` and
  `text/event-stream` in `Accept`
- return `202 Accepted` with no response body for JSON-RPC notifications
- pin the official server conformance runner to
  `@modelcontextprotocol/conformance@0.1.16` as a release gate without
  expected-failure allowances

### Sessions and request lifecycle

- make stateful streamable HTTP sessions server-issued: `initialize` must not
  send `MCP-Session-Id`; the successful response supplies it, and subsequent
  requests must echo it
- enforce `initialize` followed by `notifications/initialized` before other
  requests, both for stateful HTTP sessions and each stdio connection
- require `MCP-Protocol-Version: 2025-11-25` on stateful HTTP requests after
  initialization, and reject unknown or terminated sessions
- remove zero-session HTTP and reject the former `stateless_http:` and
  `stateless:` options; use `state_scope: :request` for request-local handler
  state while retaining a normal server-issued MCP session
- add explicit context `state_scope`, negotiated protocol, client capability,
  and client information fields; request-scoped HTTP contexts keep their stable
  non-null session id
- remove the client's initial `session_id:` option and add `sampling_tools:`,
  `sampling_context:`, and a 1 MiB default `max_sse_event_bytes:` limit

### Task compatibility

- restrict standard remote task augmentation to `tools/call`; remote
  `prompts/get` and `resources/read` task extensions have been removed
- remove the non-standard wire method `tasks/sendInput` and the corresponding
  <code>FastestMCP.Client.send_task_input/5</code> API
- retain local in-process prompt/resource task creation and
  `FastestMCP.send_task_input/5` for Elixir-owned workflows
- normalize custom `FastestMCP.TaskBackend` callbacks: `fetch_task/3` returns
  `{:ok, task}` or `{:error, reason}`, and `expire_tasks/2` returns
  `{:ok, task_ids}` or `{:error, reason}`
- reconcile persisted active tasks in bounded pages when a runtime restarts and
  fail orphaned work with `:runtime_restarted`

### HTTP safety and public interfaces

- default HTTP listeners to loopback and `allowed_hosts: :localhost`
- forward listener configuration through `bandit_options:` and add a supervised
  streamed-request timeout through `stream_request_timeout_ms:` (60 seconds by
  default)
- remove `allowed_hosts: :any` and `unsafe_allow_any_host`; use a non-empty
  concrete host list for every non-loopback listener
- expose `FastestMCP.Auth.Result`, `FastestMCP.Auth.StaticToken`,
  `FastestMCP.TaskBackend`, and `FastestMCP.TaskBackend.Memory` in HexDocs
- source the ExDoc module filter and module groups from one shared public-module
  catalog so published docs cannot drift from the navigation groups
- authenticate every inbound HTTP message and control request, bind initialized
  sessions to the authenticated identity, and apply Host/Origin validation at
  the shared public Streamable HTTP entrypoint
- reject malformed, opaque, combined, and repeated Origin headers before
  authentication; accepted origins are serialized HTTP(S) origins whose host
  is present in `allowed_hosts`
- add optional RFC 9728 Protected Resource Metadata on the MCP resource origin,
  authoritative `resource_metadata`/`scope` bearer challenges, query-token
  rejection, and expected-resource/scope input for application authenticators
- add provider candidate callbacks for deterministic all-version resolution,
  including lower-version fallback after visibility or policy filtering
- centralize duplicate component policy and preserve `:warn` as
  warn-and-replace across server, local-provider, and component-manager
  registration
- correct middleware examples to use `max_requests_per_second:`,
  `max_requests:`/`window_minutes:`, and `max_size:`

### Schema, sampling, providers, and middleware

- add JSV `0.22.x` as the sole new runtime dependency and make
  `FastestMCP.Schema` the compile-once validation boundary for Draft 2020-12
  and Draft 7; validation is non-coercing, bounded, and redacted
- vendor the immutable MCP `2025-11-25` schema from source commit
  `38c84e9f93ad191d9eb26d92b945d17bd0efcaf3` with a checked SHA-256, and cover
  the FastestMCP schema boundary with focused dialect, resolver, and limit tests
- keep those vendored bytes unchanged while applying a versioned compiled-view
  erratum for `NumberSchema.minimum`, `maximum`, and `default`: authoritative
  `schema.ts` and the elicitation specification define numbers, while the
  tagged generated JSON artifact emitted integers
- fail remote JSON Schema references closed by default; applications may opt in
  to an explicit resolver or the allowlisted HTTPS resolver with verified TLS,
  redirect refusal, and timeout/body limits
- canonicalize wire serialization around `_meta`, direct `resource_link`
  fields, object-only structured tool content, and resource templates listed
  exclusively by `resources/templates/list`; FastestMCP-only task elicitation
  state now lives under `_meta.fastestmcp`
- make component authorization fail closed: only `true` and `:ok` authorize;
  malformed returns, exceptions, throws, and exits deny access, while
  unversioned resolution may fall back from an unauthorized higher version to
  an authorized lower version
- complete sampling tool loops with `tools`, the three `toolChoice` modes,
  merged result/use metadata, explicit malformed-use errors, and an eight-round
  ceiling; advertise `sampling.tools` only when executable tools are configured
- bound both rate limiters with `max_clients: 10_000` by default and return
  `:overloaded` when live client cardinality remains full; response limiting now
  rejects limits below the smallest valid serialized tool-result envelope
- whitelist OpenAPI parameter locations without atom creation, apply override
  and style/explode rules, encode paths correctly, send scalar and array JSON
  bodies directly, and decode only JSON or `+json` responses
- reject fragment-bearing resource templates, external or cyclic filesystem
  symlinks, and skill files outside canonical roots; reloadable skill providers
  now reuse a runtime-owned metadata cache and hash only changed files
- deduplicate injected tools by component identity and use indexed exact
  Registry and atomic exact-or-template component lookups

### Bidirectional sessions and optional MCP facilities

- extend the session coordinator to own lifecycle, both request-id namespaces,
  active work, callback requests, output sinks, queued messages, progress
  tokens, logging thresholds, roots, peer tasks, URL elicitation, and SSE replay
- run inbound HTTP and stdio work under the runtime `Task.Supervisor`; support
  bidirectional cancellation and keep detached non-cancelled work supervised
  after an HTTP client disconnects
- make stdio concurrently read client responses and notifications while one
  serialized writer owns stdout; all diagnostics remain on stderr
- add `FastestMCP.Root`, `Context.list_roots/2`, cached roots, canonical
  `file://` validation, and roots-list-change refresh
- add standard form and URL elicitation, identity-bound completion through
  `FastestMCP.complete_elicitation/3`, `-32042` descriptors, HTTPS host
  allowlists through `url_elicitation_allowed_hosts:`, and completion
  notifications to the originating session only
- normalize the specification's backwards-compatible client capability
  `elicitation: {}` to effective `elicitation.form` support; URL mode still
  requires explicit `elicitation.url`
- add `FastestMCP.PeerTask` for task-augmented sampling and elicitation, with
  fetch, wait, result, cancel, and status-change helpers scoped to the exact
  originating server session, plus `Context.list_peer_tasks/2` for negotiated
  requester task listing
- add outbound ping, full sampling result validation and tool rounds, incoming
  progress callbacks, RFC 5424 logging thresholds, and bounded event rates
- add bounded logical SSE streams and same-stream `Last-Event-ID` replay; replay
  state is session-local and cleared on termination or runtime restart

### New default limits

- retain a 60-second request timeout and bound each session to 100,000 used
  request ids per direction, 128 pending callbacks, 128 active requests, 128
  peer tasks, 128 peer-task status callbacks, 1,024 queued peer messages, and
  16 MiB of queued message data
- bound each runtime to 10,000 pending callbacks, 10,000 active requests, and
  64 MiB of SSE replay data
- retain at most 256 replay events and 4 MiB per logical stream for five
  minutes; URL elicitation records expire after 15 minutes
- rate-limit outbound progress to 20 updates per second per token and inbound
  progress/logs to 100 updates per second per session
- cap JSON Schema sources at 1 MiB and nesting at 128 levels/256 references,
  with five-second compilation and one-second validation deadlines; cap opaque
  cursors at 4 KiB

### 0.1.x migration checklist

- remove `stateless_http:`, `stateless:`, `strict_input_validation:`,
  `dereference_schemas:`, initial client `session_id:`, `allowed_hosts: :any`,
  legacy REST-shaped MCP routes, batch requests, and remote `tasks/sendInput`
- use `state_scope: :request` when handler state must reset, while preserving
  the server-issued session id and initialize/initialized lifecycle
- send one JSON-RPC object per POST or stdio line; require object params and
  results, use only string/integer ids, and do not reuse ids within a session
- change tool input/output schemas to object-root JSON Schema and return
  schema-valid object `structuredContent`; values are no longer coerced
- move standard tool execution metadata to `execution.taskSupport`, keep only
  FastestMCP extensions under `_meta.fastestmcp`, and use direct standard fields
  on resource links and content blocks
- update sampling handlers to return complete `CreateMessageResult` objects
  with `role`, `content`, and `model`; form elicitation accepted content must be
  an object conforming to the requested schema
- continue list operations using the opaque `cursor` only; wire `pageSize` no
  longer controls the server-owned page size
- update custom task backends to the fallible fetch/expiry contracts described
  above and treat callback/progress/log delivery helpers as fallible operations
- configure concrete `allowed_hosts` for public mounts and, when RFC 9728
  discovery is needed, an exact `protected_resource:` plus an application-owned
  authenticator

## 0.1.2 - 2026-05-27

- refocus auth around application-owned authenticators, keeping the normalized
  `FastestMCP.Auth` contract, `FastestMCP.Auth.Result`,
  `FastestMCP.Auth.StaticToken`, and component authorization
- add function-based auth and `FastestMCP.Auth.from_assign/2` for Plug/Phoenix
  integrations
- add HTTP `auth_assigns:` support so selected `conn.assigns` can feed auth
  input without exposing assigns through handler request metadata
- remove bundled OAuth, JWT/JWKS, introspection, CIMD, and vendor auth provider
  modules, and remove the `:assent` and `:jose` dependencies
- remove the `:jason` dependency and use Elixir's native `JSON` module
- keep default HTTP auth failures on plain bearer challenges and remove built-in
  OAuth metadata/authorization/token route handling from core
- improve OpenAPI-backed tools with JSON media-type variants, form and
  multipart request bodies, cookie parameters, server variable defaults, and
  circular schema reference protection
- add multipart request support to `FastestMCP.HTTP.request/3`
- improve resource-template matching for hyphenated parameters, blank query
  values, collision rejection, and path-capture precedence
- add server `experimental_capabilities:` metadata for initialize responses
- improve mounted runtime behavior with self-mount rejection, recursive mounted
  lifespans, child-first cleanup, and stream shutdown before cleanup
- update tracing and error logging with MCP/GenAI span attributes, stable
  resource span names, `error.type`, nil-attribute filtering, arity-2 loggers,
  and per-error log levels
- document Phoenix-oriented auth, OpenAPI request serialization,
  resource-template matching, mounted lifespans, experimental capabilities,
  telemetry attributes, and error logging behavior
- add task wait behavior for input-required states, auth-scoped task ownership,
  and elicitation response metadata
- improve handler result normalization for safe finite enumerable values
- add regression coverage for auth contracts, Phoenix assign auth, task
  ownership, scalar elicitation, mounted wildcard resources, and tool/resource
  return normalization
- document auth assign bridging, task wait behavior, elicitation response
  metadata, and finite enumerable normalization

## 0.1.1 - 2026-04-17

- update broken project links in package metadata
- update the Hex package description to emphasize the BEAM-native MCP runtime,
  client, auth, and transport surfaces