Behaviour for defining individual MCP tools, resources, and prompts as separate modules.

Each component is a standalone module with its own schema and execution logic. Components are registered with a ConduitMcp.Endpoint which aggregates them into a full MCP server.

Component Types

• :tool — An MCP tool with input parameters and execution logic
• :resource — An MCP resource identified by a URI template
• :prompt — An MCP prompt with arguments that returns messages

Tool Example

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: 150
  end

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

Resource Example

defmodule MyApp.ReadUser do
  use ConduitMcp.Component,
    type: :resource,
    uri: "user://{id}",
    description: "Reads a 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

Prompt Example

defmodule MyApp.CodeReview do
  use ConduitMcp.Component, type: :prompt, description: "Code review assistant"

  schema do
    field :code, :string, "Code to review", required: true
    field :language, :string, "Programming language", default: "elixir"
  end

  @impl true
  def execute(%{code: code, language: language}, _conn) do
    {:ok, %{"messages" => [
      system("You are a code reviewer for #{language}"),
      user("Review this code:\n#{code}")
    ]}}
  end
end

Options

• :type — Required. One of :tool, :resource, :prompt
• :name — Optional. Defaults to last module segment, snake_cased
• :description — Required for tools and prompts
• :uri — Required for resources. URI template with {param} placeholders
• :mime_type — Optional for resources
• :scope — Optional space-separated OAuth scope string. Enforced by ConduitMcp.Handler for tools, resources and prompts; a request lacking the scope is rejected before execute/2 runs, and a request with no principal fails closed.
• :annotations — Optional keyword list of tool annotations (e.g., destructive: true)
• :cache — Optional modern-era cache hints, [ttl_ms: non_neg_integer, scope: :private | :public]; see ConduitMcp.CacheHints. scope: :public with a :scope is a compile error.

Generated Functions

After compilation, each component module exports:

• __component_type__/0 — Returns :tool, :resource, or :prompt
• __component_name__/0 — Returns the string name
• __component_description__/0 — Returns the description
• __component_schema__/0 — Returns the JSON Schema map for MCP clients
• __validation_schema__/0 — Returns the NimbleOptions schema for runtime validation
• __component_opts__/0 — Returns raw component options