FastestMCP

Copy Markdown View Source

FastestMCP is a BEAM-native MCP toolkit for Elixir.

It includes MCP tools, resources, prompts, middleware, auth, providers, background tasks, and streamable HTTP. 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.2"}
  ]
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

Public API

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

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 tooling
  • cluster-aware runtime behavior
  • publishing automation after the first manual release path is proven
  • custom app or UI layer

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
  • CLI tooling
  • distributed multi-node runtime behavior out of the box
  • a custom app or UI layer