FastestMCP

FastestMCP is a BEAM-native MCP toolkit for Elixir.

It keeps the useful FastMCP concepts familiar: tools, resources, prompts, middleware, auth, providers, background tasks, and streamable HTTP. The major difference is ownership. FastestMCP is built as an OTP system with supervised runtime trees, explicit request, session, and task lifetimes, and module-first server startup that fits normal Elixir applications.

Installation

Add FastestMCP to your dependencies:

def deps do
  [
    {:fastest_mcp, "~> 0.1.1"}
  ]
end

Then fetch dependencies:

mix deps.get

Quick Start

Start with a module-owned server:

defmodule MyApp.MCPServer do
  use FastestMCP.ServerModule,
    http: [port: 4100, allowed_hosts: :localhost]

  alias FastestMCP.Context

  def server(opts) do
    base_server(opts)
    |> FastestMCP.add_tool("sum", fn %{"a" => a, "b" => b}, _ctx -> a + b end)
    |> FastestMCP.add_tool("visit", fn _arguments, ctx ->
      visits = Context.get_state(ctx, :visits, 0) + 1
      :ok = Context.set_state(ctx, :visits, visits)
      %{visits: visits, server: ctx.server_name}
    end)
  end
end

children = [
  MyApp.MCPServer
]

FastestMCP.call_tool(MyApp.MCPServer, "sum", %{"a" => 20, "b" => 22})
# => 42

The full onboarding path, including transport startup and the first connected client call, lives in docs/onboarding.md.

Guides

• Onboarding
• Why FastestMCP
• Components
• Tools
• Resources
• Prompts
• Context
• Dependency Injection
• Lifespan
• Transports
• Client
• Sampling and Interaction
• Pagination
• Progress
• Logging
• Telemetry
• Dynamic Component Manager
• Auth
• Middleware
• Background Tasks
• Providers and Mounting
• Transforms
• Versioning and Visibility
• Testing
• Runtime State and Storage
• Compatibility and Scope

Public API

FastestMCP keeps the public surface curated for the first Hex release.

• FastestMCP: top-level server, transport, runtime, and task helpers
• FastestMCP.ServerModule: preferred module-owned startup wrapper
• FastestMCP.Server: low-level server definition for dynamic cases
• FastestMCP.Context: explicit request, session, auth, and task context
• FastestMCP.RequestContext: stable request snapshot derived from context
• FastestMCP.Client: connected MCP client for streamable HTTP and stdio
• FastestMCP.Auth: auth contract and shared provider wrapper
• FastestMCP.Middleware: built-in middleware constructors
• FastestMCP.Provider: provider contract for mounted and dynamic surfaces
• FastestMCP.ComponentManager: runtime mutation for live servers
• FastestMCP.Sampling: Elixir-friendly sampling helpers
• FastestMCP.Interact: higher-level elicitation helpers
• FastestMCP.SessionStateStore and FastestMCP.SessionStateStore.Memory: session-state backend contract and default backend
• FastestMCP.Tools.Result: explicit tool result helper type
• FastestMCP.Prompts.Message and FastestMCP.Prompts.Result: explicit prompt helper types
• FastestMCP.Resources.Content, FastestMCP.Resources.Result, FastestMCP.Resources.Text, FastestMCP.Resources.Binary, FastestMCP.Resources.File, FastestMCP.Resources.HTTP, and FastestMCP.Resources.Directory: explicit resource helper types
• FastestMCP.Protocol: protocol version and capability helpers
• FastestMCP.BackgroundTask: local handle for submitted task work
• FastestMCP.Transport.HTTPApp: Plug-compatible MCP app
• FastestMCP.Transport.StreamableHTTP: streamable HTTP transport
• FastestMCP.Transport.Stdio: stdio transport entrypoint

Current Scope

FastestMCP currently ships:

• module-owned and dynamic server definitions
• tools, resources, resource templates, and prompts
• middleware, providers, auth, and transport-independent execution
• explicit %FastestMCP.Context{} access to request, session, task, auth, and HTTP state
• FastestMCP.Context.current!/0, request_context/1, and client_id/1 for narrow convenience helpers where needed
• tool, prompt, and resource-template completion handlers
• explicit tool, prompt, and resource helper structs for richer payload shaping
• unified on_duplicate: handling for local server definitions, runtime component-manager mutations, and the local provider
• per-server runtime isolation, bounded concurrency, overload control, and task supervision
• streamable HTTP and stdio transports
• a Plug-first HTTP embedding surface for Bandit, Phoenix, or custom Plug apps
• a connected client for streamable HTTP and stdio
• client-side sampling, elicitation, logging, and progress callbacks
• runtime component mutation through FastestMCP.ComponentManager
• OpenAPI-backed dynamic tool generation

The main deferred items remain:

• CLI parity
• cluster-aware runtime behavior
• publishing automation after the first manual release path is proven
• custom app or UI layer parity

Standalone SSE is intentionally unsupported. HTTP means streamable HTTP only.

When To Use FastestMCP

FastestMCP is a good fit when:

• you want MCP server capabilities inside an Elixir or Phoenix system
• you want module-owned startup that plugs cleanly into application.ex
• you need supervised, crash-isolated component execution
• you want a connected Elixir client for integration tests or local tooling
• you need runtime component mutation through OTP, not an external management API
• you care about explicit session and task lifetimes with bounded overload behavior

It is not the right choice yet if you need:

• standalone SSE transport compatibility
• FastMCP CLI parity
• distributed multi-node runtime behavior out of the box
• a custom app or UI layer