How to Build a Fast.io MCP Client in Elixir

What is the Model Context Protocol?

The Model Context Protocol (MCP) is an open-source standard designed to standardize the integration of AI applications with external systems, data sources, and tools. Before MCP, developers had to write custom API wrappers for every new service an agent needed to access. Now, developers can build a single MCP client that negotiates capabilities over JSON-RPC multiple.multiple and executes remote functions easily.

For developer teams, choosing the right file sharing method directly affects project timelines and client satisfaction. Fast.io operates a fully compliant MCP server that exposes multiple specific tools for workspace manipulation. Your AI agents can perform complex tasks like uploading files, creating data rooms, running semantic searches, and granting specific access permissions through a unified protocol without writing custom REST clients.

When you implement an MCP client, your application connects to the server, announces the features it supports, and receives a structured manifest of available tools and prompts. This capability negotiation makes the integration dynamic. If Fast.io adds a new tool tomorrow, your client can discover and use it automatically without requiring any code changes on your end. The protocol supports bi-directional communication, allowing the server to push notifications and updates to your agents in real-time.

This approach changes how AI interacts with storage. Instead of pulling files locally to process them, the agent communicates with the storage environment natively. It treats the workspace as its operating system.

Why Elixir is the Perfect Fit for MCP Clients

Elixir operates on the Erlang VM (BEAM), an environment designed for highly concurrent, fault-tolerant telecommunications systems. This pedigree makes it well-suited for building reliable MCP clients that maintain persistent connections to external servers over long periods.

According to Hexdocs, Elixir processes are lightweight enough to run tens or hundreds of thousands simultaneously. Unlike operating system threads, these processes start at just a few kilobytes of memory and communicate exclusively through isolated message passing. You can run thousands of independent agent sessions on a single machine without risking a shared state deadlock or exhausting system memory.

For AI agents that often run asynchronously and require persistent state, this model is highly effective. Each agent can maintain its own isolated connection to the Fast.io server.

Key advantages of Elixir for MCP:

• Supervision Trees: Elixir applications use OTP supervision trees to guarantee high resilience and process uptime. If a network blip causes your Fast.io SSE connection to drop, the supervisor automatically restarts the client process from a known good state.
• Actor Model Concurrency: Each agent can maintain its own isolated connection state, complete with capability lists and session tokens.
• Garbage Collection: Because memory is garbage collected on a per-process basis, large JSON payloads from the Fast.io server will not cause application-wide pauses or stop-the-world events.
• Binary Pattern Matching: Parsing incoming JSON-RPC multiple.multiple payloads from the Fast.io server is fast and expressive in Elixir. This allows you to route complex nested maps easily.

The Fast.io MCP Server Architecture

Fast.io is an intelligent workspace, not just basic storage. Intelligence is native to the platform. Files are auto-indexed, searchable by meaning, and queryable through chat immediately upon upload.

The Fast.io MCP server allows external applications to programmatically control this intelligence. It exposes exactly multiple MCP tools via Streamable HTTP and Server-Sent Events (SSE). Every UI capability you see in the Fast.io web dashboard has a corresponding agent tool available over the protocol. Agents and humans share the same workspaces, tools, and intelligence.

For example, Fast.io includes built-in RAG (Retrieval-Augmented Generation). You can toggle Intelligence Mode on a workspace, and your files are auto-indexed without the need to set up a separate vector database. Your agent can invoke the search_workspace tool to retrieve semantic matches with full citations.

Other powerful capabilities include URL Import, which pulls files directly from Google Drive, OneDrive, Box, or Dropbox without routing through local I/O. This is useful for serverless agents that lack a local filesystem. The Fast.io MCP server also supports File Locks. This allows your client to acquire and release locks to prevent conflicts when multiple agents work in the same shared environment. Webhooks also let your agents receive notifications when files change, enabling reactive workflows without the overhead of constant polling.

Setting Up Your Elixir Project

To get started building your MCP client, we need to initialize a standard Mix project and pull in a few dependencies to handle HTTP connections, Server-Sent Events, and JSON parsing.

Run the following command in your terminal to create the scaffolding:

mix new fastio_mcp_client --sup
cd fastio_mcp_client

The --sup flag generates a supervised application, which is a necessary requirement for maintaining our resilient connection. Next, open your mix.exs file and add the required dependencies inside the deps function:

defp deps do
  [
    {:req, "~> 0.5.0"},
    {:jason, "~> 1.4"},
    {:websockex, "~> 0.4.3"} # Optional, if using WebSockets instead of SSE
  ]
end

We will rely heavily on the Req library because it natively supports Server-Sent Events (SSE) out of the box. This makes it easy to subscribe to the Fast.io MCP stream. Jason will handle our JSON encoding and decoding for the JSON-RPC multiple.0 payloads. After updating your dependencies, run mix deps.get to download and compile them.

Before we write our connection module, ensure you have your Fast.io API key ready. You can generate one from the Fast.io dashboard under your workspace settings.

Implementing the SSE Client with GenServer

Building an MCP client requires maintaining state and handling asynchronous network events. The perfect tool for this in Elixir is a GenServer. Here is how you can implement a basic GenServer to manage an SSE connection to the Fast.io MCP server.

First, we define our module and initialize the connection process. We will use Req to attach an asynchronous stream to our server endpoint.

defmodule FastioMcpClient.Connection do
  use GenServer
  require Logger

# Client API

def start_link(opts) do
    GenServer.start_link(__MODULE__, opts, name: __MODULE__)
  end

def send_request(method, params) do
    GenServer.call(__MODULE__, {:send_request, method, params})
  end

# Server Callbacks

@impl true
  def init(opts) do
    api_key = Keyword.fetch!(opts, :api_key)
    url = "/storage-for-agents/"
    
    # Start the async SSE stream
    req = Req.new(url: url, headers: [{"Authorization", "Bearer #{api_key}"}])
    {:ok, ref} = Req.get(req, into: fn request, response -> 
      send(self(), {:sse_chunk, response})
      {:cont, request, response}
    end, async: true)

# Our state holds the request reference, a message ID counter, and the POST endpoint
    {:ok, %{ref: ref, request_id: 1, session_id: nil, available_tools: []}}
  end
end

In this setup, the init/multiple callback immediately fires off an asynchronous GET request to the Fast.io SSE endpoint. The Req library streams chunks of data back to our GenServer by sending {:sse_chunk, response} messages continuously. We initialize our state map to track the current message ID. This is required by the JSON-RPC multiple.multiple specification for matching responses to requests.

Handling JSON-RPC 2.0 Messages and Capability Negotiation

Once the connection is established, the Fast.io server will stream JSON-RPC multiple.multiple messages down the pipe. We need to handle these messages by implementing the handle_info/multiple callback in our GenServer.

The Model Context Protocol uses Server-Sent Events to push data. When the connection opens, the server will send an initialization message containing a unique POST endpoint. We must capture this endpoint. It is where we will send all our client's JSON-RPC requests.

@impl true
def handle_info({:sse_chunk, chunk}, state) do
  # In a production system, you would properly parse the SSE format.
  # Here we assume a simplified extraction of the JSON payload string
  case parse_sse_event(chunk) do
    {:ok, "endpoint", endpoint_url} ->
      Logger.info("Received MCP POST endpoint: #{endpoint_url}")
      send_initialization(endpoint_url)
      {:noreply, %{state | session_id: endpoint_url}}
      
    {:ok, "message", payload} ->
      decoded = Jason.decode!(payload)
      new_state = handle_rpc_message(decoded, state)
      {:noreply, new_state}
      
    _ ->
      {:noreply, state}
  end
end

When our GenServer receives the endpoint, it triggers send_initialization/multiple, where we announce our capabilities. This includes telling the server whether we support resources, prompts, or tools.

We also need a set of private functions to pattern match the incoming JSON-RPC methods:

defp handle_rpc_message(%{"method" => "notifications/tools/list", "params" => params}, state) do
  tools = params["tools"] || []
  Logger.info("Discovered #{length(tools)} tools from Fast.io.")
  %{state | available_tools: tools}
end

defp handle_rpc_message(%{"id" => id, "result" => result}, state) do
  # Handle successful response to a previous request
  Logger.info("Request #{id} succeeded.")
  state
end

The powerful pattern matching in Elixir makes routing these different message types easy and readable. You never need complex switch statements. You just define functions that match the shape of the map you expect.

Executing Fast.io's 251 Tools

With the connection established and initialization complete, your Elixir application can now execute any of the 251 tools provided by the Fast.io MCP server.

To execute a tool, your client sends a standard JSON-RPC request to the POST endpoint acquired during the SSE handshake. Here is an example of how you might invoke the upload_file tool to move an asset into a shared workspace, or the search_workspace tool to use Intelligence Mode.

def invoke_tool(endpoint_url, tool_name, arguments) do
  payload = %{
    "jsonrpc" => "2.0",
    "id" => System.unique_integer([:positive]),
    "method" => "tools/call",
    "params" => %{
      "name" => tool_name,
      "arguments" => arguments
    }
  }
  
  # Use Req to send the POST request synchronously for the example
  # In a real app, you might want to handle this asynchronously
  Req.post!(endpoint_url, json: Jason.encode!(payload))
end

Because Fast.io features an intelligent workspace, uploading a file through this tool immediately triggers the built-in RAG pipeline. The file is auto-indexed and its contents become available for semantic search via the search_workspace tool right away.

If you wanted to search the workspace, you would structure your arguments like this:

invoke_tool(
  state.session_id, 
  "search_workspace", 
  %{"query" => "Q3 revenue projections", "workspace_id" => "wksp_123"}
)

The server will return a JSON-RPC response containing the semantic matches, which your Elixir client can parse and pass along to a local LLM or another part of your pipeline.

Managing Agent State with File Locks

When running multiple agents concurrently, data integrity becomes a real concern. If two agents attempt to modify the same file or data room simultaneously, you risk creating conflicts or overwriting data.

The Fast.io MCP server addresses this by providing native File Locks. Your Elixir client can invoke a tool to acquire a lock on a specific file before making modifications. If the lock is successfully acquired, the agent proceeds. If it is denied, the Elixir client can implement an exponential backoff using Process.send_after/multiple to retry the operation later.

def attempt_lock(endpoint, file_id) do
  response = invoke_tool(endpoint, "acquire_file_lock", %{"file_id" => file_id})
  
  case response.body do
    %{"result" => %{"success" => true}} -> 
      :ok
    %{"error" => _error} -> 
      Logger.warning("Lock denied, retrying in multiple seconds...")
      Process.send_after(self(), :retry_lock, 5000)
      :error
  end
end

This locking mechanism, paired with Elixir's non-blocking processes, ensures that your multi-agent systems coordinate without stepping on each other's toes.

Resiliency and Self-Healing Workspaces

One of the main reasons to build your MCP client in Elixir is to take advantage of its self-healing capabilities. When dealing with remote network connections, failures are not just possible; they are guaranteed. Web sockets close, SSE streams timeout, server restarts happen, and API rate limits get hit.

By placing our FastioMcpClient.Connection under a Supervisor, we ensure that our client never stays down. We configure a supervision tree that watches over our agent connections.

defmodule FastioMcpClient.Application do
  use Application

@impl true
  def start(_type, _args) do
    children = [
      {FastioMcpClient.Connection, [api_key: System.get_env("FASTIO_API_KEY")]}
    ]

opts = [strategy: :one_for_one, name: FastioMcpClient.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

If the connection process crashes due to a network anomaly or an unhandled JSON parsing error, the supervisor catches the exit signal and spawns a fresh process right away. This new process runs its init/multiple callback, automatically re-establishes the SSE connection, and performs the MCP handshake again.

This architecture fits well with the concept of ownership transfer in Fast.io. An agent can create an organization, build workspaces, invite humans, and transfer ownership, all running continuously in the background. Thanks to Elixir's supervision trees, your agents will continue working around the clock without human intervention.

Best Practices for Elixir MCP Clients

When finalizing your Fast.io MCP client, there are a few best practices native to the Elixir ecosystem that you should adopt.

First, implement complete logging. The Logger module in Elixir is fast. Log every tool invocation and state change, especially when capability lists are updated by the server. Fast.io provides a full audit log in its web interface, but having client-side logs is helpful for debugging agent behavior.

Second, respect rate limits. Fast.io scales well, but the free agent tier includes multiple credits per month. Ensure your client implements intelligent retries for HTTP multiple status codes. You can use Elixir's built-in timers or a library like Retry to handle backoffs smoothly.

Finally, encapsulate your JSON-RPC payloads in structs. While raw maps are easy to use initially, defining a defstruct for your Requests, Responses, and Notifications will provide better type safety and documentation for your codebase as your agent capabilities grow.