FastestMCP

MCP servers and clients for Elixir and Phoenix.

The Model Context Protocol (MCP) lets AI applications such as Claude, ChatGPT, Cursor, and AI-enabled editors use your software: the model calls your tools, reads your resources, and offers your prompts to the user. FastestMCP turns your Elixir or Phoenix application into an MCP server, with ordinary functions as handlers and OTP supervision underneath, and includes a client for calling other MCP servers.

Getting Started · Core Concepts · Phoenix · All guides

Installation

Add fastest_mcp to your dependencies in mix.exs:

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

FastestMCP requires Elixir 1.19 or later.

Quick start with Phoenix

Define a server module. Each tool is a function plus a description and a JSON Schema that tell the model how to call it. The handlers call MyApp.Notes, one of your application's contexts; Getting Started builds it as a small notes store:

# lib/my_app/mcp_server.ex
defmodule MyApp.MCPServer do
  use FastestMCP.ServerModule

  def server(opts) do
    base_server(opts)
    |> FastestMCP.add_tool(
      "search_notes",
      fn %{"query" => query}, _ctx -> %{notes: MyApp.Notes.search(query)} end,
      description: "Find the notes that contain a word or phrase.",
      input_schema: %{
        "type" => "object",
        "properties" => %{"query" => %{"type" => "string"}},
        "required" => ["query"]
      }
    )
    |> FastestMCP.add_resource_template("notes://{id}", fn %{"id" => id}, _ctx ->
      MyApp.Notes.get(id)
    end)
  end
end

Start it with your application, before the endpoint:

# In lib/my_app/application.ex
children = [
  MyApp.MCPServer,
  MyAppWeb.Endpoint
]

Route /mcp to it, in a scope of its own and without the :browser or :api pipeline; the server module is the plug of its endpoint:

# In lib/my_app_web/router.ex
scope "/" do
  forward "/mcp", MyApp.MCPServer
end

Your app now serves MCP at http://localhost:4000/mcp. Connect an MCP client to it, for example Claude Code:

claude mcp add --transport http notes http://localhost:4000/mcp

or call it from your own code and tests:

FastestMCP.call_tool!(MyApp.MCPServer, "search_notes", %{"query" => "release"})

Getting Started walks through the whole setup, including testing it, and Phoenix covers hosts, authentication, and deployment. Without Phoenix, give the server its own listener with use FastestMCP.ServerModule, http: [port: 4100], or run it over stdio; see Transports.

What you can build

You want to Use Guide
Let a model call functions in your app Tools Tools
Let an AI application read your data by URI Resources and resource templates Resources
Offer ready-made prompts to users Prompts Prompts
Serve MCP from your Phoenix app A forward in your router Phoenix
Run a local server that a desktop app launches The stdio transport Transports
Require tokens or OAuth scopes Authentication and authorization Authentication and Authorization
Log to the client, report progress, keep state The handler context Context
Share connections and services with handlers Lifespans and dependencies Lifespans and Dependencies
Ask the user to confirm, or ask the model to write Elicitation and sampling Sampling and Elicitation
Run long jobs that clients can follow and cancel Background tasks Background Tasks
Add logging, rate limits, or caching Middleware Middleware
Combine servers, proxy a remote server, or turn an OpenAPI spec into tools Providers and mounting Providers and Mounting
Change the tools on offer while the server runs Dynamic components and visibility Dynamic Components
Show an interactive UI from a tool (MCP Apps) Protocol extensions Extensions
Call other MCP servers from Elixir The client Client
Test your server In-process calls and clients Testing
Trace and monitor it Telemetry and OpenTelemetry Observability

Protocol support

FastestMCP implements MCP 2026-07-28 and 2025-11-25 over Streamable HTTP and stdio. Clients and servers agree on a version automatically, and one running server serves clients of both versions at once. See Protocol Versions and Compatibility and Scope.

Documentation

Contributing

See CONTRIBUTING.md for the checks to run and how the docs are written.

License

Apache-2.0; see LICENSE.