Claudio.MCP.ServerConfig (Claudio v0.7.0)

View Source

Structured configuration for the Anthropic MCP connector (mcp-client-2025-11-20).

The connector needs two halves in a Messages request: a server entry in mcp_servers (to_map/1) and an mcp_toolset entry in tools that references the server by name (to_toolset/1). Claudio.Messages.Request.add_mcp_server/2 emits both and declares the beta header.

Tool selection lives on the toolset: allow_tools/2 (allowlist of exact tool names), set_default_config/2, and configure_tool/3.

Example

alias Claudio.MCP.ServerConfig

server =
  ServerConfig.new("my_server", "https://mcp.example.com/sse")
  |> ServerConfig.set_auth_token("bearer-token-here")
  |> ServerConfig.allow_tools(["search_events", "fetch_data"])

Request.new("claude-opus-5-5")
|> Request.add_mcp_server(server)

Summary

Types

t()

Functions

allow_tools(config, names)

Allowlists tools by exact name: disables all tools by default and enables each named one. A later call replaces the allowlist (tools only an earlier call enabled are no longer enabled); other per-tool settings are kept.

configure_tool(config, name, settings)

Merges settings into the per-tool override for name (an exact tool name).

new(name, url)

Creates a new MCP server configuration.

set_auth_token(config, token)

Sets the OAuth bearer token the connector sends to the MCP server.

set_default_config(config, settings)

Merges settings into the toolset's default_config (applies to every tool unless overridden per tool). Supported keys include "enabled" and "defer_loading".

split_raw(server)

Splits a raw server map into {server_entry, toolset}.

to_map(config)

The mcp_servers entry for this server.

to_toolset(config)

The mcp_toolset entry (for tools) that references this server.

Types

t()

@type t() :: %Claudio.MCP.ServerConfig{
  authorization_token: String.t() | nil,
  configs: %{required(String.t()) => map()} | nil,
  default_config: map() | nil,
  name: String.t(),
  type: String.t(),
  url: String.t()
}

Functions

allow_tools(config, names)

@spec allow_tools(t(), [String.t()]) :: t()

Allowlists tools by exact name: disables all tools by default and enables each named one. A later call replaces the allowlist (tools only an earlier call enabled are no longer enabled); other per-tool settings are kept.

Raises ArgumentError on a name containing * or ?. The connector matches configs keys literally and only logs a server-side warning for unknown names, so a pattern would produce a valid request with no tools enabled.

ServerConfig.allow_tools(config, ["search_events", "fetch_data"])

configure_tool(config, name, settings)

@spec configure_tool(t(), String.t(), map()) :: t()

Merges settings into the per-tool override for name (an exact tool name).

ServerConfig.configure_tool(config, "delete_all", %{"enabled" => false})

new(name, url)

@spec new(String.t(), String.t()) :: t()

Creates a new MCP server configuration.

ServerConfig.new("my_server", "https://mcp.example.com/sse")

set_auth_token(config, token)

@spec set_auth_token(t(), String.t()) :: t()

Sets the OAuth bearer token the connector sends to the MCP server.

set_default_config(config, settings)

@spec set_default_config(t(), map()) :: t()

Merges settings into the toolset's default_config (applies to every tool unless overridden per tool). Supported keys include "enabled" and "defer_loading".

split_raw(server)

@spec split_raw(map()) :: {map(), map()}

Splits a raw server map into {server_entry, toolset}.

A legacy tool_configuration key (connector mcp-client-2025-04-04) is removed from the server entry and translated onto the toolset with a deprecation warning. Raises ArgumentError when the map has neither "name" nor :name.

to_map(config)

@spec to_map(t()) :: map()

The mcp_servers entry for this server.

to_toolset(config)

@spec to_toolset(t()) :: map()

The mcp_toolset entry (for tools) that references this server.