ExMCP - Complete Elixir implementation of the Model Context Protocol.

ExMCP enables AI models to securely interact with local and remote resources through a standardized protocol. It provides both client and server implementations with multiple transport options.

Public API

ExMCP provides a clean, focused public API. Only use these modules in your applications:

Core Modules

• ExMCP - This module (convenience functions and metadata)
• ExMCP.Client - MCP client implementation
• ExMCP.Server - MCP server helper functions
• ExMCP.Server.Handler - Callback behaviour for MCP servers
• ExMCP.Server.DSL - Declarative tool/resource/prompt definitions
• ExMCP.Transport - Transport behaviour definition

Optional Features

• ExMCP.Authorization - OAuth 2.1 authorization flows (MCP optional feature)
• ExMCP.ACP - Agent Client Protocol client and native agent helpers

Supporting Modules

• ExMCP.Content - Content type helpers (builders; advanced transform/sanitize is experimental)
• ExMCP.Types - Type definitions (stable across versions)
• ExMCP.HttpPlug - Phoenix/Plug MCP endpoint
• ExMCP.Error / ExMCP.Response - Error and response helpers

Deprecated (removed in 1.1.0)

• ExMCP.Server.Tools and related modules — use ExMCP.Server.DSL

Quick Start

Start a Client

# Connect to stdio server
{:ok, client} = ExMCP.start_client(
  transport: :stdio,
  command: ["python", "mcp-server.py"]
)

# Connect with HTTP
{:ok, client} = ExMCP.start_client(
  transport: :http,
  url: "https://api.example.com"
)

Start a Server

{:ok, server} = ExMCP.start_server(
  handler: MyApp.MCPHandler,
  transport: :stdio
)

BEAM-Local Communication

{:ok, server} = MyServer.start_link(transport: :beam)

{:ok, client} = ExMCP.start_client(
  transport: :beam,
  server: server
)

{:ok, tools} = ExMCP.Client.list_tools(client)

Protocol Versions

ExMCP supports multiple MCP protocol versions:

• 2024-11-05 - Base MCP features
• 2025-03-26 - Previous stable (subscriptions, roots, logging, batch support)
• 2025-06-18 - Structured output, OAuth 2.1, elicitation, no batch
• 2025-11-25 - Current latest supported version (tasks, icons, URL elicitation)

See the README.md for a complete feature comparison chart.

Features

• Tools - Register and execute functions with parameters
• Resources - List and read data from various sources
• Prompts - Manage reusable prompt templates
• Sampling - Direct LLM integration for response generation
• Roots - URI-based resource boundaries
• Subscriptions - Monitor resources for changes
• Progress - Track long-running operations
• Notifications - Real-time updates for changes
• BEAM-local MCP - High-performance Elixir-to-Elixir communication

Transport Options

• stdio - Process communication (standard MCP)
• HTTP/SSE - Web-friendly transport (standard MCP)
• BEAM-local MCP - Direct Erlang process communication (ExMCP extension)

Examples

Basic Client Usage

{:ok, client} = ExMCP.start_client(transport: :stdio, command: ["mcp-server"])

# List and call tools
{:ok, %{tools: tools}} = ExMCP.Client.list_tools(client)
{:ok, result} = ExMCP.Client.call_tool(client, "search", %{query: "elixir"})

# Read resources
{:ok, content} = ExMCP.Client.read_resource(client, "file:///data.json")

Basic Server Usage

Tip

Most servers are easier to write with the DSL:

defmodule MyServer do
  use ExMCP.Server.Handler
  use ExMCP.Server.DSL, name: "my-server", version: "1.0.0"

  tool "echo", "Echo the message" do
    param :message, :string, required: true
    run fn %{message: msg}, state ->
      {:ok, %{content: [%{type: "text", text: msg}]}, state}
    end
  end
end

{:ok, server} = MyServer.start_link(transport: :stdio)

defmodule MyHandler do
  use ExMCP.Server.Handler

  @impl true
  def handle_initialize(_params, state) do
    {:ok, %{
      protocolVersion: ExMCP.protocol_version(),
      serverInfo: %{name: "my-handler", version: "1.0.0"},
      capabilities: %{tools: %{}}
    }, state}
  end

  @impl true
  def handle_list_tools(_cursor, state) do
    tools = [%{name: "echo", description: "Echo input", inputSchema: %{type: "object"}}]
    {:ok, tools, nil, state}
  end

  @impl true
  def handle_call_tool("echo", params, state) do
    {:ok, %{content: [%{type: "text", text: params["message"]}]}, state}
  end
end

{:ok, server} = ExMCP.start_server(handler: MyHandler, transport: :stdio)

BEAM-Local Service

defmodule MyService do
  use ExMCP.Server.Handler
  use ExMCP.Server.DSL

  tool "ping", "Health check" do
    run fn _args, state ->
      {:ok, %{content: [%{type: "text", text: "pong"}]}, state}
    end
  end
end

{:ok, server} = MyService.start_link(transport: :beam)
{:ok, client} = ExMCP.start_client(transport: :beam, server: server)
{:ok, result} = ExMCP.Client.call_tool(client, "ping", %{})