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 (retained through 1.x; planned for removal in 2.0.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"],
  protocol_mode: :prefer_modern
)

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

Start a Server

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

BEAM-Local Communication

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

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

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

Protocol Versions

ExMCP supports two wire-incompatible MCP eras:

• 2026-07-28 - Latest stable revision; stateless discovery, per-request context, result envelopes, MRTR, and subscriptions/listen
• 2025-11-25 - Newest legacy revision; tasks, icons, and URL elicitation
• 2025-06-18 - Structured output, OAuth 2.1, elicitation, no batch
• 2025-03-26 - Subscriptions, roots, logging, and batch support
• 2024-11-05 - Initial stable MCP revision

rc.7 defaults to protocol_mode: :prefer_modern, which tries the modern revision first and retains evidence-based legacy fallback. Use protocol_mode: :modern_only for a closed modern ecosystem or protocol_mode: :legacy_only to preserve the legacy protocol era. Exact rc.5 wire and session behavior still requires package rollback to 1.0.0-rc.5.

See the Configuration and Migration guides for the era comparison and rollout policy.

Features

• Tools - Register and execute functions with parameters
• Resources - List and read data from various sources
• Prompts - Manage reusable prompt templates
• Sampling - Protocol-deprecated in MCP 2026-07-28; retained throughout ExMCP 1.x for compatibility. Prefer direct LLM provider APIs for new code
• Roots - Protocol-deprecated in MCP 2026-07-28; retained throughout ExMCP 1.x. Prefer tool parameters, resource URIs, or server configuration
• 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)
• Streamable HTTP - 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"],
    protocol_mode: :prefer_modern
  )

# 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, protocol_mode: :prefer_modern)

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,
    protocol_mode: :prefer_modern
  )

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, protocol_mode: :prefer_modern)

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