API Reference

A quick reference for the most commonly used functions. Looking for more detailed examples? Check out our guides.

Client API

Starting a Client

Add Backplane.McpProtocol.Client directly to your supervision tree:

{Backplane.McpProtocol.Client,
 name: MyApp.MCPClient,
 transport: {:stdio, command: "cmd", args: ["arg1"]},
 client_info: %{"name" => "MyApp", "version" => "1.0.0"},
 protocol_version: :auto}

Required Options:

name - Process name (atom or {:via, ...} tuple)
transport - Transport configuration tuple
client_info - Map with "name" and "version" keys

Optional Options:

capabilities - Capabilities map (default: %{})
protocol_version - :auto (default) or an explicitly pinned MCP version

Transport Options:

{:stdio, command: "cmd", args: ["arg1", "arg2"]}
{:streamable_http, base_url: "http://localhost:8000"}
{:websocket, base_url: "ws://localhost:8000"}
{:sse, base_url: "http://localhost:8000"} (deprecated — use :streamable_http instead)

2026-07-28 is supported over stdio and Streamable HTTP. Pin a legacy version for WebSocket or SSE.

Client Functions

All functions take a client process name or PID as the first argument:

Backplane.McpProtocol.Client.list_tools(MyApp.MCPClient)

Connection Management:

ping/1,2 - Check responsiveness on legacy peers; unsupported by 2026-07-28
close/1 - Close the connection gracefully
await_ready/1,2 - Wait for modern discovery or legacy initialization
get_protocol_info/1,2 - Inspect the selected era, version, and peer metadata
set_log_level/2 - Set a legacy peer's logging threshold; unsupported by 2026-07-28

Discovery:

get_server_info/1,2 - Get server information
get_server_capabilities/1,2 - Get server capabilities

Tools:

list_tools/1,2 - List available tools
call_tool/2,3,4 - Call a tool with arguments

Resources:

list_resources/1,2 - List available resources (supports pagination)
read_resource/2,3 - Read a specific resource

Prompts:

list_prompts/1,2 - List available prompts (supports pagination)
get_prompt/2,3,4 - Get a prompt with arguments

Autocompletion:

complete/3,4 - Get completion suggestions

Modern Subscriptions:

listen_subscriptions/2,3 - Open and acknowledge a subscriptions/listen stream
close_subscription/2,3 - Cancel a subscription using its transport-specific mechanism

Subscription owners receive {:mcp_subscription, handle, notification} and {:mcp_subscription_closed, handle, reason} messages. Connection loss closes the handle; callers must listen again after reconnecting if they still want events.

Options

Functions that make requests accept options:

timeout: milliseconds - Request timeout (default: 30_000)
meta: map - Application request metadata; modern protocol-reserved metadata is merged by the client
progress: keyword - Progress token and optional callback

Protocol Selection

:auto starts with modern server/discover, negotiates 2026-07-28, and uses legacy initialization only after a protocol-defined legacy signal. Explicit version strings are pins and never fall back across eras. Modern Streamable HTTP sends MCP-Protocol-Version, Mcp-Method, Mcp-Name, and safe schema-declared Mcp-Param-* mirrors.

Server API

Module Definition

use Backplane.McpProtocol.Server, options

Required Options:

name - Your server name (string)
version - Your server version (string)
capabilities - List of capabilities to expose

Starting a Server

{MyApp.Server, transport: transport_config}

Transport Options:

:stdio - Standard input/output
{:streamable_http, port: 8080} - HTTP server
:none - No transport (for embedding)

Server Callbacks

@behaviour Backplane.McpProtocol.Server.Behaviour

# Optional initialization
def init(arg, frame) do
  {:ok, frame}
end

# Optional initialization for one stateless 2026-07-28 request
def init_request(request_context, frame) do
  {:ok, frame}
end

# Handle incoming requests (optional)
def handle_request(request, frame) do
  {:reply, result, frame}
end

# Handle notifications (optional)
def handle_notification(notification, frame) do
  {:noreply, frame}
end

Component Definition

Tools

use Backplane.McpProtocol.Server.Component, type: :tool

alias Backplane.McpProtocol.Server.Response

# Schema definition
schema do
  field :name, :string, required: true
  field :age, :integer, min: 0
end

# Execution callback
def execute(params, frame) do
  {:reply, Response.text(Response.tool(), result), frame}
end

Resources

use Backplane.McpProtocol.Server.Component,
  type: :resource,
  uri: "resource://type/name"

alias Backplane.McpProtocol.Server.Response

# Read callback
def read(params, frame) do
  {:reply, Response.text(Response.resource(), content), frame}
end

Prompts

use Backplane.McpProtocol.Server.Component, type: :prompt

alias Backplane.McpProtocol.Server.Response

# Schema for arguments
schema do
  field :context, :string
end

# Get messages callback
def get_messages(params, frame) do
  response = Response.prompt() |> Response.user_message("...")
  {:reply, response, frame}
end

Component Registration

defmodule MyApp.Server do
  use Backplane.McpProtocol.Server, ...

  # Register components
  component MyApp.MyTool
  component MyApp.MyResource
  component MyApp.MyPrompt
end

Schema DSL

The DSL covers the common Peri-compatible subset. Modern tools also preserve raw JSON Schema 2020-12 maps on the wire, including unknown keywords, $defs, composition, and references. A client that cannot compile a received schema retains the tool but disables local validation for it. External network $ref resolution is disabled by default. Modern structuredContent accepts every JSON value, including explicit null.

Available field types and validations:

schema do
  field :string_field, :string,
    required: true,
    min_length: 1,
    max_length: 100,
    regex: ~r/pattern/,
    description: "A string field"

  field :number_field, :number,
    min: 0,
    max: 100,
    description: "A number field"

  field :integer_field, :integer,
    min: 0,
    max: 1000,
    description: "An integer field"

  field :boolean_field, :boolean,
    default: false,
    description: "A boolean field"

  field :enum_field, :enum,
    required: true,
    description: "An enum field",
    values: ~w(option1 option2 option3)

  field :list_field, {:list, :string},
    description: "A list of strings"

  # Nested objects using embeds_one
  embeds_one :profile, required: true do
    field :name, :string, required: true
    field :age, :integer, min: 0, max: 150
  end

  # Arrays of objects using embeds_many
  embeds_many :tags do
    field :name, :string, required: true
    field :value, :string
  end
end

Return Values

Client Returns

Most client functions return:

{:ok, %{result: data}} - Successful response
{:ok, %{is_error: true, result: error}} - Tool-level error
{:error, reason} - Protocol or connection error

Server Returns

Component callbacks return:

{:reply, %Response{}, frame} - Success with response
{:noreply, frame} - No reply needed
{:error, %Error{}, frame} - Error with structured error

Server callbacks return:

{:reply, result, frame} - Reply with result
{:noreply, frame} - No reply
{:stop, reason, frame} - Stop the server

Error Handling

Errors are automatically formatted according to MCP protocol. You can return:

String error messages
Error tuples
Exceptions (will be caught and formatted)

Useful Mix Tasks

Interactive Testing:

mix backplane.mcp_protocol.stdio.interactive Module - Test with STDIO
mix backplane.mcp_protocol.streamable_http.interactive Module - Test with HTTP

Development:

mix compile --force - Recompile all components
mix test - Run tests

The modern io.modelcontextprotocol/tasks extension is not enabled in this release. Legacy Tasks remain supported for 2025-11-25 peers.

Need More?

This reference covers the essential API. For detailed examples and patterns:

Remember: the protocol complexity is handled for you. Focus on what your application does best.

← Previous Page Recipes

Next Page → Authorization