Manages MCP server instances and routes tool calls. More...

#include <entropic/mcp/server_manager.h>

Public Member Functions
	ServerManager (const PermissionsConfig &permissions, const std::filesystem::path &project_dir)
	Construct with permission config and project directory.

void	register_server (std::unique_ptr< MCPServerBase > server)
	Register a built-in server (in-process, ownership transferred).

void	init_builtins (const MCPConfig &mcp_config, const std::vector< std::string > &tier_names, const std::string &data_dir)
	Register built-in servers based on config flags.

entropic_error_t	load_plugins (const MCPConfig &mcp_config)
	Load the dlopen plugins listed in `mcp.plugins` (gh#133).

void	initialize ()
	Initialize all registered servers.

std::string	list_tools () const
	List all tools from all connected servers.

std::string	execute (const std::string &tool_name, const std::string &args_json)
	Execute a tool call via the appropriate server.

MCPServerBase *	get_server (const std::string &name) const
	Get a registered in-process server by name.

std::vector< std::string >	server_names () const
	List registered server names (in-process + external).

const std::filesystem::path &	project_dir () const
	Get the project root directory.

std::string	get_tool_schema (const std::string &tool_name) const
	Get the JSON Schema for a tool's input parameters.

bool	is_explicitly_allowed (const std::string &tool_name, const std::string &args_json) const
	Check if tool is explicitly allowed (skip prompting).

std::string	get_permission_pattern (const std::string &tool_name, const std::string &args_json) const
	Generate permission pattern via server class delegation.

bool	skip_duplicate_check (const std::string &tool_name) const
	Check if tool should skip duplicate detection.

MCPAccessLevel	get_required_access_level (const std::string &tool_name) const
	Get the required access level for a tool.

void	add_permission (const std::string &pattern, bool allow)
	Add a runtime permission pattern.

void	shutdown ()
	Shutdown all servers (in-process + external).

std::vector< std::string >	connect_external_server (const ExternalServerConfig &spec)
	Connect to an external MCP server at runtime (canonical spec-based API).

std::vector< std::string >	connect_external_server (const std::string &name, const std::string &command="", const std::vector< std::string > &args={}, const std::string &url="")
	Connect by primitive parameters (legacy convenience).

void	disconnect_external_server (const std::string &name)
	Disconnect and remove an external server.

std::map< std::string, ServerInfo >	list_server_info () const
	Get snapshot of all servers with current status.

void	process_health_events ()
	Process pending health events (call from engine loop).

void	set_mcp_config (const MCPConfig &config)
	Set MCP config for external server initialization.

void	interrupt_external_tools ()
	Abort in-flight tool calls across every external MCP client.

Detailed Description

Manages MCP server instances and routes tool calls.

Owns both in-process servers (v1.8.5) and external MCP clients (v1.8.7). Tool routing by server prefix is uniform across both. External servers discovered from .mcp.json and YAML config.

Version: 1.8.7

Definition at line 59 of file server_manager.h.

Constructor & Destructor Documentation

◆ ServerManager()

entropic::ServerManager::ServerManager	(	const PermissionsConfig &	permissions,
		const std::filesystem::path &	project_dir
	)

Construct with permission config and project directory.

Parameters

permissions	Permission configuration.
project_dir	Project root directory.

Version: 1.8.5

Parameters

permissions	Permission configuration.
project_dir	Project root directory. @dg_internal

Version: 1.8.5

Definition at line 32 of file server_manager.cpp.

Member Function Documentation

◆ add_permission()

void entropic::ServerManager::add_permission	(	const std::string &	pattern,
		bool	allow
	)

Add a runtime permission pattern.

Parameters

pattern	Permission pattern.
allow	true for allow list, false for deny list.

Version: 1.8.5

Backs the operator's "always allow/deny" decision — the pattern takes effect on the next call.

Parameters

pattern	Permission pattern, normally the one get_permission_pattern() produced for this call.
allow	true for the allow list, false for the deny list. @req REQ-MCP-009

Version: 1.8.5

Definition at line 660 of file server_manager.cpp.

◆ connect_external_server() [1/2]

std::vector< std::string > entropic::ServerManager::connect_external_server ( const ExternalServerConfig & spec )

Connect to an external MCP server at runtime (canonical spec-based API).

Connect (canonical spec-based) — Issue #9, v2.1.4.

Issue #9 (v2.1.4): unifies the runtime API and config-file paths. The full ExternalServerConfig is honored — including env, which pre-2.1.4 was silently dropped from the 4-arg path. The ServerConfig.name field is required.

Parameters

spec	Full server config (transport/command/args/env/url).

Returns: List of tool names registered from the server.

Version: 2.1.4

The full ExternalServerConfig is honored. Replaces the pre-2.1.4 runtime path which silently dropped env (and any future spec field).

Parameters

spec	External server configuration.

Returns: The connected server's prefixed tool names; an empty vector when the name is already registered (refused rather than shadowed), when the connection failed, or when the tool list could not be parsed. @req REQ-MCP-025 @req REQ-MCP-007

Version: 2.1.4

Definition at line 938 of file server_manager.cpp.

◆ connect_external_server() [2/2]

std::vector< std::string > entropic::ServerManager::connect_external_server	(	const std::string &	name,
		const std::string &	command = `""`,
		const std::vector< std::string > &	args = `{}`,
		const std::string &	url = `""`
	)

Connect by primitive parameters (legacy convenience).

Legacy primitive-args overload — forwards to spec-based API.

Forwards to the spec-based overload above; provided for backwards-compat with in-tree callers. Pre-2.1.4 callers that passed only command/args/url get default-empty env. Prefer the spec-based overload for new code. (#9, v2.1.4)

Parameters

name	Unique server name.
command	Stdio command (mutually exclusive with url).
args	Stdio command arguments.
url	SSE endpoint URL (mutually exclusive with command).

Returns: List of tool names registered from the server.

Version: 2.1.4

Retained for in-tree callers that pre-date #9. New code should use the spec-based overload.

@dg_internal

Version: 2.1.4

Definition at line 980 of file server_manager.cpp.

◆ disconnect_external_server()

void entropic::ServerManager::disconnect_external_server ( const std::string & name )

Disconnect and remove an external server.

Parameters

name	Server name to disconnect.

Version: 1.8.7

Parameters

name	Server name. @dg_internal

Version: 1.8.7

Definition at line 999 of file server_manager.cpp.

◆ execute()

std::string entropic::ServerManager::execute	(	const std::string &	tool_name,
		const std::string &	args_json
	)

Execute a tool call via the appropriate server.

Parameters

tool_name	Fully-qualified name (e.g., "filesystem.read_file").
args_json	JSON arguments string.

Returns: ServerResponse JSON envelope.

Version: 1.8.5

Checks permissions before execution. Returns error JSON if denied or server not found.

Builds the <tool>:<args-summary> pattern and consults the deny list BEFORE routing, so a denied call short-circuits without ever reaching the server. A call matching neither list is not denied here — the engine's approval callback does the prompting.

Parameters

tool_name	Fully-qualified name (`<server>.<tool>`).
args_json	JSON arguments.

Returns: ServerResponse JSON envelope — the server's own on the routed path, or one whose result is "Error: Permission denied for <tool>" with empty directives when the deny list matched. @req REQ-MCP-009 @req REQ-MCP-007 @req REQ-MCP-002

Version: 1.8.7

Definition at line 287 of file server_manager.cpp.

◆ get_permission_pattern()

std::string entropic::ServerManager::get_permission_pattern	(	const std::string &	tool_name,
		const std::string &	args_json
	)		const

Generate permission pattern via server class delegation.

Generate permission pattern via server delegation.

Parameters

tool_name	Fully-qualified tool name.
args_json	Tool arguments as JSON.

Returns: Permission pattern string.

Version: 1.8.5

The pattern an "always allow/deny" decision is stored under is chosen by the OWNING server, so a server can pick a finer granularity than the tool name (BashServer keys on the base command).

Parameters

tool_name	Fully-qualified tool name.
args_json	Tool arguments.

Returns: The owning in-process server's pattern when the prefix is known; the fully-qualified tool name as a fallback when it is not (plugin/external/unknown prefix). @req REQ-MCP-009

Version: 1.8.5

Definition at line 590 of file server_manager.cpp.

◆ get_required_access_level()

MCPAccessLevel entropic::ServerManager::get_required_access_level ( const std::string & tool_name ) const

Get the required access level for a tool.

Parameters

tool_name Fully-qualified tool name (e.g., "filesystem.read_file").

Returns: MCPAccessLevel required, or WRITE if tool not found.

Version: 1.9.4

Falling back to WRITE means an unknown tool name cannot be used to slip a call past a READ-only key set.

Parameters

tool_name Fully-qualified tool name.

Returns: The tool's declared MCPAccessLevel when it resolves; MCPAccessLevel::WRITE for an unknown server or tool. @req REQ-MCP-011

Version: 1.9.4

Definition at line 634 of file server_manager.cpp.

◆ get_server()

MCPServerBase * entropic::ServerManager::get_server ( const std::string & name ) const

Get a registered in-process server by name.

Parameters

name	Server name (e.g., "entropic", "filesystem").

Returns: Server pointer, or nullptr if not found.

Version: 2.0.6

Parameters

name	Server name (the routing prefix, no tool suffix).

Returns: Non-owning pointer to the in-process server, or nullptr when the name is unknown OR names a plugin/external server — those are peers, not MCPServerBase subclasses. @req REQ-MCP-007

Version: 2.0.6

Definition at line 313 of file server_manager.cpp.

◆ get_tool_schema()

std::string entropic::ServerManager::get_tool_schema ( const std::string & tool_name ) const

Get the JSON Schema for a tool's input parameters.

Parameters

tool_name Fully-qualified tool name.

Returns: input_schema JSON string, or empty if tool not found.

Version: 2.0.6

Resolves from the in-process registry first, then falls back to the plugin's own descriptor list, so a plugin tool is argument-validated on exactly the same terms a built-in is.

Parameters

tool_name Fully-qualified tool name (<server>.<tool>).

Returns: The tool's declared inputSchema JSON; an empty string for an unknown server or tool — which ToolExecutor::check_schema reads as "nothing to validate". @req REQ-MCP-008 @req REQ-MCP-013

Version: 2.10.1

Definition at line 355 of file server_manager.cpp.

◆ init_builtins()

void entropic::ServerManager::init_builtins	(	const MCPConfig &	mcp,
		const std::vector< std::string > &	tier_names,
		const std::string &	data_dir
	)

Register built-in servers based on config flags.

Creates and registers enabled built-in servers (entropic, filesystem, bash, git, diagnostics, web). Called by the facade after construction.

Parameters

mcp_config	MCP config with enable flags.
tier_names	Tier names for entropic server schemas.
data_dir	Bundled data directory path.

Version: 2.0.1

The six in-process servers are all MCPServerBase subclasses, so each arrives with dispatch, envelope shape and anchoring already provided by the base and only its own tools and overrides on top.

Parameters

mcp	MCP config with enable flags — a disabled server is never constructed, so its tools never appear in list_tools().
tier_names	Tier names for the entropic server (drives whether delegate/pipeline are registered at all).
data_dir	Bundled data directory holding the tool descriptors. @req REQ-MCP-001 @req REQ-MCP-007

Version: 2.0.1

Definition at line 54 of file server_manager.cpp.

◆ initialize()

void entropic::ServerManager::initialize ( )

Initialize all registered servers.

Initialize all registered servers + external connections.

Version: 1.8.5

@dg_internal

Version: 1.8.7

Definition at line 158 of file server_manager.cpp.

◆ interrupt_external_tools()

void entropic::ServerManager::interrupt_external_tools ( )

Abort in-flight tool calls across every external MCP client.

Signal every external client to cancel its in-flight tool.

Invoked from the engine's interrupt path so Ctrl+C unwinds docs_server.py / bash etc. within ~100ms instead of waiting out the transport timeout. (P1-10, 2.0.6-rc16)

@utility

Version: 2.0.6-rc16

Called by AgentEngine::interrupt() via a facade-wired callback so tool dispatches to docs_server.py / bash / git unwind within ~100ms of Ctrl+C instead of running to completion. (P1-10, 2.0.6-rc16)

@req REQ-MCP-025

Version: 2.0.6-rc16

Definition at line 790 of file server_manager.cpp.

◆ is_explicitly_allowed()

bool entropic::ServerManager::is_explicitly_allowed	(	const std::string &	tool_name,
		const std::string &	args_json
	)		const

Check if tool is explicitly allowed (skip prompting).

Check if tool is explicitly allowed.

Parameters

tool_name	Fully-qualified tool name.
args_json	Tool arguments as JSON.

Returns: true if in allow list.

Version: 1.8.5

Builds the same <tool>:<args-summary> pattern execute() uses, so an argument-level allow entry matches here on exactly the terms it will match at dispatch.

Parameters

tool_name	Fully-qualified tool name.
args_json	Tool arguments.

Returns: true when the operator's allow list matches this call, false otherwise — false means "not pre-approved", not "denied". @req REQ-MCP-009

Version: 1.8.5

Definition at line 568 of file server_manager.cpp.

◆ list_server_info()

std::map< std::string, ServerInfo > entropic::ServerManager::list_server_info ( ) const

Get snapshot of all servers with current status.

Returns: Map of server name to ServerInfo.

Version: 1.8.7

Returns: One ServerInfo per registered server across all three kinds, keyed by name — external entries carry their live transport, status and source; in-process servers report in_process/connected/builtin; plugins report plugin/plugin plus the .so path so entropic inspect can tell them apart. @req REQ-MCP-007

Version: 2.10.1

Definition at line 1030 of file server_manager.cpp.

◆ list_tools()

std::string entropic::ServerManager::list_tools ( ) const

List all tools from all connected servers.

List tools from all servers (in-process + plugin + external).

Returns: JSON array string of tool definitions.

Version: 1.8.5

Concatenates all three server kinds so the model sees one flat tool list and never has to know which kind backs a given tool.

Returns: JSON array string of fully-qualified <server>.<tool> descriptors from every in-process server, every loaded plugin and every connected external client; "[]" when nothing is registered. @req REQ-MCP-007

Version: 2.10.1

Definition at line 251 of file server_manager.cpp.

◆ load_plugins()

entropic_error_t entropic::ServerManager::load_plugins ( const MCPConfig & mcp )

Load the dlopen plugins listed in mcp.plugins (gh#133).

Load the dlopen plugins listed in mcp.plugins (gh#133).

Each path is opened, version-checked against ENTROPIC_MCP_PLUGIN_API_VERSION, and registered under the name its entropic_mcp_server_name() reports; the plugin's tools then route as <name>.<tool> like any other server's.

Every path is attempted so one bad plugin does not hide the diagnosis of the rest, and each failure is logged with its path. The FIRST failure's code is returned — a configured plugin that fails to load is never skipped silently, because that would leave the operator's stated intent unmet with no signal.

Parameters

mcp_config MCP config carrying the plugin path list.

Returns: ENTROPIC_OK when every plugin loaded (including the vacuous empty-list case), otherwise the first failure's typed code.

Version: 2.10.1

A configured-but-absent plugin would leave the operator's stated intent unmet with no signal, so every failure is typed and logged with its path. Every configured path is attempted — one broken plugin must not hide the diagnosis of the rest — and a plugin whose reported name collides with an already-registered in-process, plugin or external server is refused rather than allowed to shadow it.

Parameters

mcp	MCP config carrying the plugin path list.

Returns: ENTROPIC_OK when every configured plugin loaded (and vacuously for an empty list); otherwise the FIRST failure's typed code — ENTROPIC_ERROR_PLUGIN_LOAD_FAILED for a dlopen failure, missing entry point, null instance or name collision, ENTROPIC_ERROR_PLUGIN_VERSION_MISMATCH for a version mismatch. @req REQ-MCP-005

Version: 2.10.1

Definition at line 103 of file server_manager.cpp.

◆ process_health_events()

void entropic::ServerManager::process_health_events ( )

Process pending health events (call from engine loop).

Process pending health events.

Version: 1.8.7

Drained on the engine thread, which is what keeps the monitor thread from mutating engine state across threads.

@req REQ-MCP-025

Version: 1.8.7

Definition at line 1070 of file server_manager.cpp.

◆ project_dir()

const std::filesystem::path & entropic::ServerManager::project_dir ( ) const

inline

Get the project root directory.

Returns: Project directory path. @utility

Version: 2.0.6

Definition at line 161 of file server_manager.h.

◆ register_server()

void entropic::ServerManager::register_server ( std::unique_ptr< MCPServerBase > server )

Register a built-in server (in-process, ownership transferred).

Register a built-in server.

Parameters

server Server instance.

Version: 1.8.5

Parameters

server Server instance (ownership transferred). @dg_internal

Version: 1.8.5

Definition at line 142 of file server_manager.cpp.

◆ server_names()

std::vector< std::string > entropic::ServerManager::server_names ( ) const

List registered server names (in-process + external).

List all registered server names.

Returns: Server names.

Version: 2.0.6

Returns: Every routable prefix across all three kinds — in-process servers, then dlopen plugins, then external clients (connected or not); empty when none are registered. @req REQ-MCP-007

Version: 2.10.1

Definition at line 326 of file server_manager.cpp.

◆ set_mcp_config()

void entropic::ServerManager::set_mcp_config ( const MCPConfig & config )

Set MCP config for external server initialization.

Parameters

config MCP configuration with external_servers.

Version: 1.8.7

Parameters

config MCP configuration. @dg_internal

Version: 1.8.7

Definition at line 776 of file server_manager.cpp.

◆ shutdown()

void entropic::ServerManager::shutdown ( )

Shutdown all servers (in-process + external).

Version: 1.8.7

Ordered teardown: health monitor stopped, external clients disconnected, then plugin instances destroyed and their libraries dlclosed BEFORE the in-process servers, so nothing can call into an unmapped .so.

@req REQ-MCP-006 @req REQ-MCP-025

Version: 2.10.1

Definition at line 677 of file server_manager.cpp.

◆ skip_duplicate_check()

bool entropic::ServerManager::skip_duplicate_check ( const std::string & tool_name ) const

Check if tool should skip duplicate detection.

Parameters

tool_name Fully-qualified tool name.

Returns: true if duplicate check should be skipped.

Version: 1.8.5

Parameters

tool_name Fully-qualified tool name.

Returns: The owning server's skip_duplicate_check answer for the local tool name; false when the prefix is not an in-process server, i.e. plugin and external tools are always duplicate-checked. @req REQ-MCP-015

Version: 1.8.5

Definition at line 611 of file server_manager.cpp.

The documentation for this class was generated from the following files:

entropic/mcp/server_manager.h
mcp/server_manager.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ServerManager()

Member Function Documentation

◆ add_permission()

◆ connect_external_server() [1/2]

◆ connect_external_server() [2/2]

◆ disconnect_external_server()

◆ execute()

◆ get_permission_pattern()

◆ get_required_access_level()

◆ get_server()

◆ get_tool_schema()

◆ init_builtins()

◆ initialize()

◆ interrupt_external_tools()

◆ is_explicitly_allowed()

◆ list_server_info()

◆ list_tools()

◆ load_plugins()

◆ process_health_events()

◆ project_dir()

◆ register_server()

◆ server_names()

◆ set_mcp_config()

◆ shutdown()

◆ skip_duplicate_check()