Compatibility and Scope

Copy Markdown View Source

FastestMCP targets MCP server behavior plus the Elixir-native companion surfaces required to use that server plane cleanly from Elixir code.

Compatibility is the default for protocol-visible behavior, but divergence is allowed when a convention would fight OTP, explicit failure semantics, or normal Elixir application structure.

Compatibility Rules

  • compatibility is the default
  • divergence must be intentional, documented, and tested
  • deprecated surfaces are not revived without a current Elixir use case
  • public Elixir APIs should stay idiomatic while preserving the underlying MCP contract
  • FastestMCP-specific wire extensions, such as _meta.fastestmcp, are part of the public transport contract and should stay consistent across transports

Included Surface

The active compatibility target includes:

  • server declaration and lifecycle
  • tools, resources, resource templates, and prompts
  • tool, prompt, and resource-template completions
  • middleware, providers, auth, and transport-independent execution
  • explicit request, session, and task context handling
  • request-context snapshots and narrow current-context helpers for nested code
  • streamable HTTP and stdio server behavior
  • per-server runtime isolation, overload handling, and task supervision
  • connected client support for streamable HTTP and stdio
  • connected client completions and session-scoped resource subscriptions
  • client-side sampling, elicitation, log, and progress callbacks
  • server-side sampling and interaction helpers
  • runtime component mutation through FastestMCP.ComponentManager
  • explicit tool, prompt, and resource helper types for richer payload shaping
  • session-state backend configuration through FastestMCP.SessionStateStore
  • unified on_duplicate: semantics for local server and runtime component registration
  • centralized protocol version and capability helpers
  • explicit experimental capability advertisement through server metadata
  • native regression coverage plus live HTTP and conformance lanes

Explicitly Deferred

The following are intentionally outside the current milestone:

  • CLI tooling
  • cluster-aware runtime behavior
  • publishing automation after the first manual Hex release is proven
  • custom app or UI layer
  • deprecated compatibility behaviors

Intentional Elixir-native Divergences

  • No standalone SSE transport. The supported HTTP transport is streamable HTTP only.
  • No signature rewriting or annotation-based dependency injection. Elixir keeps explicit %FastestMCP.Context{} and FastestMCP.add_dependency/3.
  • Convenience exists only as narrow helpers such as Context.current!/0, Context.request_context/1, and Context.client_id/1. Explicit handler ctx remains the primary style.
  • HTTP integration stays Plug-first.
  • No external component management REST API. Runtime mutation lives inside the supervised runtime through FastestMCP.ComponentManager.
  • Client ergonomics are session-first and GenServer-based.

Reference Boundary

The compatibility target remains server-focused. The newer Elixir-native companion surfaces, such as the connected client and component manager, are covered by native FastestMCP tests.

Current State

Current status:

  • replacement-grade server plane is implemented for the active scope
  • connected client support exists for streamable HTTP and stdio
  • completion exists for tools, prompts, and resource templates
  • sampling and elicitation helpers are implemented for server-side usage
  • runtime component mutation is implemented through FastestMCP.ComponentManager
  • explicit tool, prompt, and resource helper modules are part of the curated public API
  • session-state storage is configurable; broader runtime storage is still local
  • standalone SSE remains an intentional non-goal

Anything not listed above should be treated as deferred or intentionally out of scope until documented otherwise.

Why This Shape

This page owns the explicit boundary. The rationale page explains the design philosophy, but this page is the contract for what FastestMCP supports, what it deliberately does not support, and what remains outside the first release.