ArborMCP

ArborMCP provides Elixir clients and servers for the Model Context Protocol, with stdio, Streamable HTTP and BEAM-local transports. Its Hex package is arbor_mcp; its Elixir module namespace is Arbor.MCP.*.

Version 2 release candidate. ArborMCP 2.0.0-rc.4 is published on Hex for downstream integration testing, with ArborRPC on its independent 1.x line. Stable arbor_mcp 2.0 has not been released. The runtime/scheduler redesign and accepted API cleanup are implemented; the roadmap and release checklist describe remaining stable qualification.

ExMCP 1.x remains maintained on codex/maintenance-1.x, with backported fixes and compatible minor releases. Migration to v2 is optional; see the maintenance policy.

ACP clients, agents and the optional vendor adapter bundle are developed in ArborACP. MCP and ACP depend on the small shared ArborRPC package and can be installed independently. ArborRPC has its own repository, with the arbor_rpc Mix project at the repository root.

Upgrading from ex_mcp 1.x? Start with the v1-to-v2 migration guide. It covers package selection, namespace and configuration changes, supervision, HTTP mounting, removed APIs and the RC testing checklist. The RC notes describe the candidate's qualification status and known limits.

Installation

For reproducible downstream RC testing:

defp deps do
  [{:arbor_mcp, "== 2.0.0-rc.4"}]
end

Run mix deps.get. ArborRPC resolves transitively from Hex; add ArborACP or its optional adapter bundle only when your application uses them. The original 2.0.0-rc.1 candidate is retired, with its tag and archive preserved.

For development, clone the default branch and resolve dependencies normally:

git clone https://github.com/trust-arbor/arbor_mcp.git
cd arbor_mcp
mix deps.get
mix compile
mix test

ARBOR_RPC_PATH optionally selects a local ArborRPC checkout. See the development guide for local source overrides and releasing for package checks without those overrides.

The supported minimum is Elixir 1.17 with Erlang/OTP 27. Protocol output uses OTP's JSON encoder. The CI matrix checks multiple Elixir/OTP versions; passing CI and the release gates are required before publishing 2.0.

On macOS/Darwin and Linux, installing the transitive arbor_rpc source package requires a C17 compiler (cc, or the executable selected by CC), including for HTTP-only and BEAM-only applications. Source archives contain reviewed C source, not prebuilt helpers. An installed release includes the built helper and needs no runtime compiler. Windows native subprocess operations are unsupported; framing is separate. Only the qualified platform/architecture matrix is supported.

Client example

{:ok, client} =
  Arbor.MCP.Client.start_link(
    transport: :stdio,
    command: ["mcp-server"],
    protocol_mode: :prefer_modern
  )

{:ok, tools} = Arbor.MCP.Client.list_tools(client, format: :map)
{:ok, result} = Arbor.MCP.Client.call_tool(client, "echo", %{"message" => "hello"}, format: :map)
Arbor.MCP.Client.stop(client)

The latest stable MCP revision is 2026-07-28. :prefer_modern allows evidence-based fallback to the legacy protocol era; :modern_only and :legacy_only select an era explicitly. Library version 2 and the MCP wire revision are separate version identifiers.

Public entrypoints

Use Arbor.MCP.Client for connection, protocol operations and explicit client conveniences; use Arbor.MCP.Server for startup, supervision, controls, statistics and shutdown. Server.Handler defines callbacks and Server.DSL adds declarations. Canonical Client operations preserve complete responses; call_content, read_content, tool_definitions and resource_definitions extract explicitly. Root client operations remain compatibility wrappers with their original behavior. See the entrypoint migration table.

Ordinary Client list_* methods preserve one response page. Explicit Client.all_tools/2, all_resources/2, all_resource_templates/2 and all_prompts/2 collect lists across opaque cursors within finite page, item, byte and total-time limits. See the public API migration guide.

Servers and transports

Handlers use Arbor.MCP.Server.Handler and the declarative Arbor.MCP.Server.DSL to define tools, resources and prompts. HTTP, stdio and BEAM use a supervised Runtime per server, bounded handler scheduling and explicit session/subscription storage contracts. Follow the roadmap for the accepted contract.

HTTP applications mount Arbor.MCP.HttpPlug with an explicit Runtime inside an existing Plug/Phoenix server. Standalone HTTP listeners are optional. Install the selected Cowboy or Bandit dependency and choose http_adapter: :cowboy or :bandit; Cowboy remains the default. See the HTTP listener guide for startup, shutdown and mounted-host ownership, and the transport guide for transport contracts.

Guides and examples

• Migrate from v1 to v2
• Version 2 release candidate
• Quickstart
• User guide
• Phoenix mounting
• Server DSL
• Runtime operations
• Configuration
• Security
• Examples
• Development
• Troubleshooting
• Changelog

Published 1.x API documentation is available at hexdocs.pm/ex_mcp. It describes the previous package and namespace. The v2 migration guide is available in this checkout and is included in the package and ExDoc documentation.

For v2 API documentation from the checkout, run mix docs --warnings-as-errors after fetching development dependencies. The original RC API docs are at hexdocs.pm/arbor_mcp/2.0.0-rc.1. The current RC API docs are at hexdocs.pm/arbor_mcp/2.0.0-rc.4. The documentation index separates guides, contributor checks and release policy.

AI agent guidance

The package ships usage rules for supported APIs, result formats, lifecycle and DSL conventions. They are also an ExDoc guide. Downstream projects with UsageRules installed as optional development tooling can add this to their mix.exs project configuration:

usage_rules: [file: "AGENTS.md", usage_rules: [:arbor_mcp]]

Then run mix usage_rules.sync. Add other Arbor packages you use to the list. UsageRules 1.2 requires Elixir 1.18 or newer; shipping these rules adds no dependency and preserves ArborMCP's Elixir 1.17 minimum.

Reporting issues

Report suspected vulnerabilities through the private vulnerability reporting form. Use GitHub issues for other bugs and feature requests.

Licensed under the MIT license.