FastestMCP (fastest_mcp v0.1.2)

The high-level API.

FastestMCP is the top of the public surface. Most users start here and stay here for day-to-day work:

building a %FastestMCP.Server{} with the pipeline-style builder API
starting and stopping a running server
dispatching in-process MCP operations
exposing HTTP or stdio transports
working with background tasks
preparing sampling tools

Under that facade, the runtime is composed of a few lower-level pieces:

FastestMCP.Server - immutable server definitions
FastestMCP.ServerModule - module-owned server API with generated OTP helpers
FastestMCP.Context - explicit request, session, auth, and task context
FastestMCP.RequestContext - stable request snapshot derived from FastestMCP.Context
FastestMCP.Client - connected MCP client
FastestMCP.Tools.Result - explicit tool result helper
FastestMCP.Prompts.Message and FastestMCP.Prompts.Result - explicit prompt result helpers
FastestMCP.Resources.Content, FastestMCP.Resources.Result, and the FastestMCP.Resources.* helper modules - explicit resource result helpers, including file, HTTP, and directory-backed resources
the shared operation pipeline used by local dispatch

The design goal is simple: keep the public API small while keeping the runtime explicitly OTP-shaped.

Examples

Build a small server definition:

server =
  FastestMCP.server("docs")
  |> FastestMCP.add_tool("sum", fn %{"a" => a, "b" => b}, _ctx -> a + b end)

Start it and call it in process:

{:ok, _pid} = FastestMCP.start_server(server)
42 = FastestMCP.call_tool("docs", "sum", %{"a" => 20, "b" => 22})
:ok = FastestMCP.stop_server("docs")

Expose the same runtime over HTTP:

plug = FastestMCP.http_app("docs", allowed_hosts: :localhost)
child = {Bandit, plug: plug, port: 4100}

Prepare local tools for sampling:

tools = FastestMCP.prepare_sampling_tools("docs")

Resolve tool-argument completion values:

FastestMCP.complete(
  "docs",
  %{type: "ref/tool", name: "deploy"},
  %{name: "environment", value: "prev"}
)

When To Drop Lower

Use this module when you want the shortest path.

Drop to FastestMCP.Server when you need to work with the immutable server struct directly. Drop to FastestMCP.ServerModule when the server belongs to your application supervision tree. Drop to FastestMCP.Context when you are inside a handler and need request or session state. Reach for the tool, prompt, and resource helper modules when a component needs explicit control over result envelopes.

Summary

Functions

add_auth(server, provider_or_auth, opts \\ [])

Adds auth configuration to the current definition.

add_dependency(server, name, resolver)

Registers a dependency resolver on the current definition.

add_http_route(server, method, path, handler)

Adds an HTTP route to the current definition.

add_lifespan(server, lifespan)

Adds lifespan hooks to the current definition.

add_lifespan(server, enter, exit)

add_middleware(server, middleware)

Adds middleware to the current definition.

add_prompt(server, name, handler, opts \\ [])

Adds a prompt component to the current definition.

add_provider(server, provider)

Adds a provider to the current definition.

add_provider_transform(provider, transform)

Adds a transform to a provider wrapper.

add_resource(server, uri, handler, opts \\ [])

Adds a resource component to the current definition.

add_resource_template(server, uri_template, handler, opts \\ [])

Adds a resource-template component to the current definition.

add_tool(server, name, handler, opts \\ [])

Adds a tool component to the current definition.

add_transform(server, transform)

Adds a transform to the current definition.

await_task(task, timeout \\ 5000)

Waits for a background task to finish.

await_task(server_name, task_id, timeout, opts \\ [])

call_tool(server_name, name, arguments \\ %{}, opts \\ [])

Calls a tool with the given arguments.

cancel_task(task)

Cancels a background task.

cancel_task(server_name, task_id, opts \\ [])

complete(server_name, ref, argument, opts \\ [])

Resolves completion values for tool arguments, prompt arguments, or resource-template parameters.

component_manager(server_name)

Fetches the live component manager for a running server.

current_protocol_version()

Returns the current MCP protocol version.

disable_components(server_name, opts \\ [])

Disables matching components for all sessions on the running server.

enable_components(server_name, opts \\ [])

Enables matching components for all sessions on the running server.

fetch_task(task)

Fetches background-task state.

fetch_task(server_name, task_id, opts \\ [])

from_openapi(openapi_spec, opts \\ [])

Builds an OpenAPI-backed provider from a loaded specification.

http_app(server_name, opts \\ [])

Builds the main HTTP app for a running server.

initialize(server_name, params \\ %{}, opts \\ [])

Runs the MCP initialize handshake.

list_prompts(server_name, opts \\ [])

Lists visible prompts.

list_resource_templates(server_name, opts \\ [])

Lists visible resource templates.

list_resources(server_name, opts \\ [])

Lists visible resources.

list_tasks(server_name, opts \\ [])

Lists background tasks.

list_tools(server_name, opts \\ [])

Lists visible tools.

mount(server, mounted_server, opts \\ [])

Mounts another server or provider-backed definition.

notify_resource_updated(server_name, uri)

Notifies subscribed sessions that one concrete resource URI changed.

ping(server_name, params \\ %{}, opts \\ [])

Runs a ping request.

prepare_sampling_tools(server_or_tools, opts \\ [])

Normalizes sampling-tool definitions for later sampling calls.

read_resource(server_name, uri, opts \\ [])

Reads a resource by URI.

render_prompt(server_name, name, arguments \\ %{}, opts \\ [])

Renders a prompt with the given arguments.

reset_component_visibility(server_name)

Clears all server-scoped component visibility rules.

send_task_input(server_name, task_id, action, content \\ nil, opts \\ [])

Sends input to a background task waiting for user interaction.

server(name, opts \\ [])

Builds a new server definition.

start_server(server_or_module, opts \\ [])

Starts a server runtime.

stdio_dispatch(server_name, request, opts \\ [])

Dispatches one stdio request against a running server.

stop_server(server_name)

Stops a running server runtime.

streamable_http_child_spec(server_name, opts \\ [])

Returns a child spec for the streamable HTTP transport.

subscribe_task_notifications(server_name, session_id, opts \\ [])

Starts a subscriber for background-task notifications.

task_notification_subscriber_count(server_name)

Returns the number of active task-notification subscribers.

task_result(task)

Returns the normalized result for a background task.

task_result(server_name, task_id, opts \\ [])

well_known_http_child_spec(server_name, opts \\ [])

Returns a child spec for the well-known HTTP transport.