API Reference

Copy Markdown

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

Client API

Starting a Client

Add Anubis.Client directly to your supervision tree:

{Anubis.Client,
 name: MyApp.MCPClient,
 transport: {:stdio, command: "cmd", args: ["arg1"]},
 client_info: %{"name" => "MyApp", "version" => "1.0.0"},
 protocol_version: "2025-06-18"}

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 - MCP protocol version (default: latest)

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)

Client Functions

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

Anubis.Client.ping(MyApp.MCPClient)
Anubis.Client.list_tools(MyApp.MCPClient)

Connection Management:

  • ping/0,1 - Check if server is responsive
  • close/0,1 - Close the connection gracefully

Discovery:

  • get_server_info/0,1 - Get server information
  • get_server_capabilities/0,1 - Get server capabilities

Tools:

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

Resources:

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

Prompts:

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

Autocompletion:

  • complete/2,3 - Get completion suggestions

Options

Functions that make requests accept options:

  • timeout: milliseconds - Request timeout (default: 30_000)

Server API

Module Definition

use Anubis.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 Anubis.Server.Behaviour

# Optional initialization
def init(arg, 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 Anubis.Server.Component, type: :tool

alias Anubis.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 Anubis.Server.Component,
  type: :resource,
  uri: "resource://type/name"

alias Anubis.Server.Response

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

Prompts

use Anubis.Server.Component, type: :prompt

alias Anubis.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 Anubis.Server, ...

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

Schema DSL

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 anubis.stdio.interactive Module - Test with STDIO
  • mix anubis.streamable_http.interactive Module - Test with HTTP

Development:

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

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.