ConduitMCP

An Elixir implementation of the Model Context Protocol (MCP) specification (2025-11-25). Build MCP servers to expose tools, resources, and prompts to LLM applications like Claude Desktop, VS Code, and Cursor.

• MCP Apps — Tools can return interactive UI rendered as sandboxed iframes in host clients
• Three Ways to Build — DSL macros, raw callbacks, or component modules — pick your level of control
• Full MCP Spec — Tools, resources, prompts, completion, logging, subscriptions (MCP 2025-11-25 + 2025-06-18)
• Runtime Validation — NimbleOptions-powered param validation with type coercion and custom constraints
• Stateless Architecture — Pure functions, no processes, maximum concurrency via Bandit
• Authentication — Bearer tokens, API keys, OAuth 2.1 (RFC 9728), custom verification
• Rate Limiting — HTTP-level and message-level rate limiting with Hammer
• Session Management — Pluggable session stores (ETS, Redis, PostgreSQL, Mnesia)
• Observability — Telemetry events, optional Prometheus metrics via PromEx
• Phoenix Ready — Drop-in integration with Phoenix routers
• CORS & Security — Configurable origins, preflight handling, origin validation

def deps do
  [
    {:conduit_mcp, "~> 0.10"}
  ]
end

Requires Elixir ~> 1.18.

The core library needs nothing beyond the block above. These features are compiled in only when their dependency is present, so add the ones you need before you configure the feature:

Adding one of these later requires a forced rebuild. These modules are guarded by if Code.ensure_loaded?(Dep), which is evaluated once — when :conduit_mcp is compiled inside your project's _build. Mix does not recompile an already-built dependency when you add a new one, so run:

mix deps.get
mix deps.compile conduit_mcp --force

Skipping this leaves the feature absent. ConduitMCP detects that at init/1 and raises ConduitMcp.OptionalDependencyError naming the missing dependency and this command, rather than failing at request time.

Define a server in one module:

defmodule MyServer do
  use ConduitMcp.Server

  tool "echo", "Echo a message" do
    param :message, :string, "Message to echo", required: true
    handle fn _conn, %{"message" => msg} -> text(msg) end
  end
end

Run it with Bandit:

# lib/my_app/application.ex
children = [
  {Bandit, plug: {ConduitMcp.Transport.StreamableHTTP, server_module: MyServer}, port: 4000}
]

Try it:

curl -s -X POST http://localhost:4000/ -H 'Content-Type: application/json' -d '{
  "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": {"name": "echo", "arguments": {"message": "hello"}}
}'

For multi-tool servers, authentication, sessions, OAuth, MCP Apps, and more, see the guides and examples.

ConduitMCP is pre-1.0. Most APIs are stable; the following are explicitly experimental and may change before 1.0:

• ConduitMcp.Tasks and ConduitMcp.Tasks.Janitor — task lifecycle is new in MCP spec 2025-11-25 and the surface area may evolve.
• ConduitMcp.Client — message builders for server-to-client requests (sampling, elicitation, roots). The bidirectional transport these depend on is not yet wired through Streamable HTTP.
• ConduitMcp.Cancellation — the cooperative cancellation model may grow a more direct preemption path.

Breaking changes between minor versions will be called out in CHANGELOG.md.

ConduitMCP gives you three modes. Each is a complete, independent way to build an MCP server — pick whichever fits your project.

Everything in one module with compile-time macros. Schemas and validation generated automatically.

defmodule MyApp.MCPServer do
  use ConduitMcp.Server

  tool "greet", "Greet someone" do
    param :name, :string, "Person's name", required: true
    param :style, :string, "Greeting style", enum: ["formal", "casual"]

    handle fn _conn, params ->
      name = params["name"]
      style = params["style"] || "casual"
      greeting = if style == "formal", do: "Good day", else: "Hey"
      text("#{greeting}, #{name}!")
    end
  end

  prompt "code_review", "Code review assistant" do
    arg :code, :string, "Code to review", required: true
    arg :language, :string, "Language", default: "elixir"

    get fn _conn, args ->
      [
        system("You are a code reviewer"),
        user("Review this #{args["language"]} code:\n#{args["code"]}")
      ]
    end
  end

  resource "user://{id}" do
    description "User profile"
    mime_type "application/json"

    read fn _conn, params, _opts ->
      user = MyApp.Users.get!(params["id"])
      json(user)
    end
  end
end

Response helpers (auto-imported): text/1, json/1, image/1, audio/2, error/1, raw/1, raw_resource/2, system/1, user/1, assistant/1 — see Responses for details and custom response patterns.

Full control. You implement callbacks directly with raw JSON Schema maps. No compile-time magic.

defmodule MyApp.MCPServer do
  use ConduitMcp.Server, dsl: false

  @tools [
    %{
      "name" => "greet",
      "description" => "Greet someone",
      "inputSchema" => %{
        "type" => "object",
        "properties" => %{"name" => %{"type" => "string"}},
        "required" => ["name"]
      }
    }
  ]

  @impl true
  def handle_list_tools(_conn), do: {:ok, %{"tools" => @tools}}

  @impl true
  def handle_call_tool(_conn, "greet", %{"name" => name}) do
    {:ok, %{"content" => [%{"type" => "text", "text" => "Hello, #{name}!"}]}}
  end
end

Each tool, resource, or prompt is its own module. An Endpoint aggregates them with declarative config for rate limiting, auth, and server metadata.

# Each tool is its own module
defmodule MyApp.Echo do
  use ConduitMcp.Component, type: :tool, description: "Echoes text back"

  schema do
    field :text, :string, "The text to echo", required: true, max_length: 500
  end

  @impl true
  def execute(%{text: text}, _conn) do
    text(text)
  end
end

defmodule MyApp.ReadUser do
  use ConduitMcp.Component,
    type: :resource,
    uri: "user://{id}",
    description: "User by ID",
    mime_type: "application/json"

  @impl true
  def execute(%{id: id}, _conn) do
    user = MyApp.Users.get!(id)
    {:ok, %{"contents" => [%{
      "uri" => "user://#{id}",
      "mimeType" => "application/json",
      "text" => JSON.encode!(user)
    }]}}
  end
end

# Endpoint aggregates components
defmodule MyApp.MCPServer do
  use ConduitMcp.Endpoint,
    name: "My App",
    version: "1.0.0",
    rate_limit: [backend: MyApp.RateLimiter, limit: 60, scale: 60_000],
    message_rate_limit: [backend: MyApp.RateLimiter, limit: 50, scale: 300_000]

  component MyApp.Echo
  component MyApp.ReadUser
end

Endpoint config is auto-extracted by transports — no duplication needed:

{Bandit,
 plug: {ConduitMcp.Transport.StreamableHTTP, server_module: MyApp.MCPServer},
 port: 4001}

See the Endpoint Mode Guide for full details on components, schema DSL, and options.

# lib/my_app/application.ex
def start(_type, _args) do
  children = [
    {Bandit,
     plug: {ConduitMcp.Transport.StreamableHTTP, server_module: MyApp.MCPServer},
     port: 4001}
  ]

  Supervisor.start_link(children, strategy: :one_for_one)
end

# lib/my_app_web/router.ex
scope "/mcp" do
  forward "/", ConduitMcp.Transport.StreamableHTTP,
    server_module: MyApp.MCPServer,
    auth: [strategy: :bearer_token, token: System.get_env("MCP_AUTH_TOKEN")]
end

Both transports support authentication, rate limiting, CORS, and session management.

All tool/resource/prompt handlers return {:ok, map()} or {:error, map()}. Helper macros are imported automatically in DSL and Endpoint modes.

Use texts/1 to return multiple text items in a single response:

{:ok, %{"content" => texts(["Line 1", "Line 2", "Line 3"])}}
# => {:ok, %{"content" => [%{"type" => "text", "text" => "Line 1"}, ...]}}

For maximum control, skip the helpers entirely and return the map yourself:

def execute(_params, _conn) do
  {:ok, %{
    "content" => [
      %{"type" => "text", "text" => "Here is the chart:"},
      %{"type" => "image", "data" => base64_png, "mimeType" => "image/png"},
      %{"type" => "text", "text" => "Analysis complete."}
    ]
  }}
end

The raw/1 helper is a shortcut for returning any map without MCP content wrapping — useful for debugging or non-standard responses:

raw(%{"custom_key" => "custom_value", "nested" => %{"data" => [1, 2, 3]}})
# => {:ok, %{"custom_key" => "custom_value", "nested" => %{"data" => [1, 2, 3]}}}

Note: raw/1 bypasses the MCP content structure. Clients expecting standard "content" arrays won't parse it correctly. Use it for debugging or custom integrations.

Standard JSON-RPC 2.0 error codes used by the protocol:

All three modes support runtime validation via NimbleOptions. DSL and Endpoint modes generate validation schemas automatically. Manual mode can opt in via __validation_schema_for_tool__/1.

An :object param declared with a block validates its nested fields — required, types, and the constraints above — to any depth, and rejects undeclared keys:

param :user, :object, "User data", required: true do
  field :name, :string, "Full name", required: true
  field :address, :object, "Address" do
    field :city, :string, "City", required: true
  end
end

Declared with no block it is an open bag: any keys accepted, nothing enforced. additional_properties: true combines the two — declared fields are enforced and undeclared keys pass through to the handler. The generated JSON Schema always emits additionalProperties, so it agrees with what the server enforces.

Array item types are declared with items:

param :rows, :array, "Rows" do
  items :object do
    field :id, :integer, "Row id", required: true
  end
end

Item schemas are published for clients but not enforced server-side — NimbleOptions cannot attach a nested schema to a list element type.

Handlers always receive string keys, at every depth.

Enabled by default. Automatic conversion: "25" → 25, "true" → true, "85.5" → 85.5.

config :conduit_mcp, :validation,
  runtime_validation: true,
  strict_mode: true,
  type_coercion: true,
  log_validation_errors: false

Configure in transport options or Endpoint use opts:

# Bearer token
auth: [strategy: :bearer_token, token: "your-secret-token"]

# API key
auth: [strategy: :api_key, api_key: "your-key", header: "x-api-key"]

# Custom verification
auth: [strategy: :function, verify: fn token ->
  case MyApp.Auth.verify(token) do
    {:ok, user} -> {:ok, user}
    _ -> {:error, "Invalid token"}
  end
end]

# OAuth 2.1 (RFC 9728)
auth: [strategy: :oauth, issuer: "https://auth.example.com", audience: "my-app"]

Authenticated user is available via conn.assigns[:current_user] in all callbacks.

Two layers using Hammer (optional dependency):

# Setup: add {:hammer, "~> 7.2"} to deps, then:
defmodule MyApp.RateLimiter do
  use Hammer, backend: :ets
end

HTTP rate limiting — limits raw connections:

rate_limit: [backend: MyApp.RateLimiter, limit: 100, scale: 60_000]

Message rate limiting — limits MCP method calls (tool calls, reads, prompts):

message_rate_limit: [
  backend: MyApp.RateLimiter,
  limit: 50,
  scale: 300_000,
  excluded_methods: ["initialize", "ping"]
]

Both support per-user keying via :key_func. Returns HTTP 429 with Retry-After header.

StreamableHTTP supports server-side sessions with pluggable stores. Sessions are off unless you configure them:

session: []                                 # Opt in, using ConduitMcp.Session.EtsStore
session: [store: MyApp.RedisSessionStore]   # Opt in with a custom store
session: false                              # Off — same as omitting :session

Any other :session value (true, a map) raises ArgumentError at the transport's init/1, so the mistake fails at boot.

See guides: Multi-Node Sessions

Events emitted for monitoring:

Optional Prometheus metrics via ConduitMcp.PromEx — see module docs.

{
  "mcpServers": {
    "my-app": {
      "url": "http://localhost:4001/",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

{
  "mcpServers": {
    "my-app": {
      "command": "elixir",
      "args": ["/path/to/your/server.exs"]
    }
  }
}

ConduitMCP implements the full MCP specification:

• Choosing a Mode — DSL vs Manual vs Endpoint comparison
• Endpoint Mode — Component modules, schema DSL, full walkthrough
• Authentication — All auth strategies in detail
• Rate Limiting — HTTP and message rate limiting
• Multi-Node Sessions — Redis, PostgreSQL, Mnesia session stores
• Oban Tasks — Long-running tasks with Oban
• MCP Apps — Interactive UI from MCP tools

• API Documentation
• Changelog
• MCP Specification

• Simple Server Example
• Phoenix Integration
• MCP Apps Demo

Apache License 2.0