Pure C interface contract for MCP server plugins. More...

#include <stddef.h>
#include <entropic/entropic_export.h>
#include <entropic/types/error.h>

Include dependency graph for i_mcp_server.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	entropic_state_provider_t
	Read-only engine state provider for introspection tools. More...

Macros
#define	ENTROPIC_MCP_PLUGIN_API_VERSION 1
	Current MCP plugin API version.

Typedefs
typedef struct entropic_mcp_server *	entropic_mcp_server_t
	Opaque handle to an MCP server instance.

Functions
ENTROPIC_EXPORT int	entropic_plugin_api_version (void)
	Report the plugin API version this plugin was built against.

ENTROPIC_EXPORT entropic_mcp_server_t	entropic_create_server (void)
	Construct a server instance.

ENTROPIC_EXPORT const char *	entropic_mcp_server_name (entropic_mcp_server_t server)
	Get the server name.

ENTROPIC_EXPORT char *	entropic_mcp_server_list_tools (entropic_mcp_server_t server)
	List tools as JSON array string.

ENTROPIC_EXPORT char *	entropic_mcp_server_execute (entropic_mcp_server_t server, const char tool_name, const char args_json)
	Execute a tool and return ServerResponse JSON envelope.

ENTROPIC_EXPORT entropic_error_t	entropic_mcp_server_configure (entropic_mcp_server_t server, const char *config_json)
	Configure a server instance after creation.

ENTROPIC_EXPORT entropic_error_t	entropic_mcp_server_set_working_dir (entropic_mcp_server_t server, const char *path)
	Set the working directory for a server.

ENTROPIC_EXPORT void	entropic_mcp_server_destroy (entropic_mcp_server_t server)
	Destroy a server instance.

ENTROPIC_EXPORT void	entropic_free (void *ptr)
	Free a string allocated by the server.

Detailed Description

Pure C interface contract for MCP server plugins.

Every MCP server plugin (.so) implements this interface. ServerManager discovers plugins via dlopen and calls these functions through the opaque handle.

Loading a plugin (gh#133, v2.10.1): List the .so under mcp.plugins in the engine config:
mcp:

plugins:

- /path/to/libmy_mcp_server.so

At startup ServerManager dlopens each entry, checks entropic_plugin_api_version() against ENTROPIC_MCP_PLUGIN_API_VERSION, resolves the entry points below, and registers the server under the name returned by entropic_mcp_server_name(). Its tools are then addressable as <name>.<tool> exactly like a built-in server's.

A plugin that fails to open, is missing an entry point, or reports a different API version is rejected LOUDLY with ENTROPIC_ERROR_PLUGIN_LOAD_FAILED / ENTROPIC_ERROR_PLUGIN_VERSION_MISMATCH — never skipped silently, since a configured-but-absent plugin would leave the operator's stated intent unmet with no signal.

Before v2.10.1 this header documented the dlopen contract but no loader existed; a conformant .so could not be loaded by anything.

Memory ownership

Strings returned by list_tools and execute are caller-owned. Free with entropic_free().
Strings returned by name are server-owned (valid for handle lifetime).
Input strings (tool_name, args_json, config_json) are borrowed for the duration of the call only.

Threading (v2.10.1): The engine serialises calls into a given server instance — execute(), configure(), and set_working_dir() never run concurrently on the same handle, so a plugin needs no internal locking for its own state. No ordering is guaranteed between distinct handles, and the calling thread is not fixed, so a plugin must not use thread-local state to carry data across calls. destroy() happens-after every other call on that handle.

Tool descriptor shape: Tool definitions returned by list_tools use inputSchema (camelCase), matching the bundled descriptors in data/tools/*/*.json:
[{"name":"echo","description":"...",

"inputSchema":{"type":"object","properties":{...},"required":[...]}}]

Plugin export requirements: Every MCP server .so must export all nine entry points declared below. They carry ENTROPIC_EXPORT so that a plugin defining them plainly —
extern "C" int entropic_plugin_api_version() { return 1; }

entropic_plugin_api_version
ENTROPIC_EXPORT int entropic_plugin_api_version(void)
Report the plugin API version this plugin was built against.
Definition inference_c_api.cpp:603

— still exports them under -fvisibility=hidden, which is how most plugin projects build. Without the attribute on these declarations such a definition inherits hidden visibility and the resulting .so exports nothing at all, making every dlsym in the loader fail.

ABI lock: Function signatures and the entropic_mcp_server_t opaque-handle type are LOCKED at API version 1. Any change to a function declaration, struct member layout, or the macro/typedef contracts in this header is a breaking change that requires bumping entropic_plugin_api_version(). Comment-only changes are safe. Cross-version compatibility test: a plugin built against 2.1.4 headers MUST dlopen cleanly into a 2.1.5 engine (verified comment-only diff in gh release v2.1.5 review).

The v2.10.1 addition of ENTROPIC_EXPORT to these declarations is NOT a version bump: it changes symbol visibility only, leaving every signature, calling convention, and the opaque-handle type untouched. A plugin built against pre-2.10.1 headers that exported its entry points by other means (its own visibility attribute, or a version script) dlopens into a v2.10.1 engine unchanged.

Version: 2.10.1

Definition in file i_mcp_server.h.

Macro Definition Documentation

◆ ENTROPIC_MCP_PLUGIN_API_VERSION

#define ENTROPIC_MCP_PLUGIN_API_VERSION 1

Current MCP plugin API version.

Bumped when MCPServerBase or ToolBase virtual method signatures change. A plugin built against an older vtable loaded into a newer engine will be rejected with ENTROPIC_ERROR_PLUGIN_VERSION_MISMATCH.

Version: 1.8.5

Definition at line 320 of file i_mcp_server.h.

Typedef Documentation

◆ entropic_mcp_server_t

typedef struct entropic_mcp_server* entropic_mcp_server_t

Opaque handle to an MCP server instance.

Version: 1.8.5

Definition at line 101 of file i_mcp_server.h.

Function Documentation

◆ entropic_create_server()

ENTROPIC_EXPORT entropic_mcp_server_t entropic_create_server ( void )

Construct a server instance.

Implemented BY THE PLUGIN, called by the engine's loader once per configured .so. Parameterless for ABI uniformity — pass construction parameters via entropic_mcp_server_configure() instead. The returned handle is owned by the engine and released with entropic_mcp_server_destroy().

Declared here (v2.10.1) rather than described only in prose so that plugin definitions pick up ENTROPIC_EXPORT from this header.

Returns: Opaque server handle, or NULL on failure.

Version: 2.10.1

◆ entropic_free()

ENTROPIC_EXPORT void entropic_free ( void * ptr )

Free a string allocated by the server.

Parameters

ptr	Pointer returned by list_tools or execute. NULL is a safe no-op.

Version: 1.8.5

Free a string allocated by the server.

Free memory allocated by the engine or entropic_alloc().

@req REQ-API-008 @req REQ-ABI-001

Version: 1.8.0

Definition at line 2018 of file entropic.cpp.

◆ entropic_mcp_server_configure()

ENTROPIC_EXPORT entropic_error_t entropic_mcp_server_configure	(	entropic_mcp_server_t	server,
		const char *	config_json
	)

Configure a server instance after creation.

Parameters

server	Server handle.
config_json	JSON configuration string.

Returns: ENTROPIC_OK on success.

Version: 1.8.5

Some servers need construction parameters (root_dir, config). The entropic_create_server() signature is parameterless for ABI uniformity. Per-server configuration is passed via this call.

Configure a server instance after creation.

Parameters

server	Server handle.
config_json	Configuration JSON.

Returns: ENTROPIC_OK on success. @dg_internal

Version: 1.8.5

Definition at line 107 of file mcp_c_api.cpp.

◆ entropic_mcp_server_destroy()

ENTROPIC_EXPORT void entropic_mcp_server_destroy ( entropic_mcp_server_t server )

Destroy a server instance.

Parameters

server Server handle to destroy. NULL is a safe no-op.

Version: 1.8.5

Parameters

server Server handle. @dg_internal

Version: 1.8.5

Definition at line 142 of file mcp_c_api.cpp.

◆ entropic_mcp_server_execute()

ENTROPIC_EXPORT char * entropic_mcp_server_execute	(	entropic_mcp_server_t	server,
		const char *	tool_name,
		const char *	args_json
	)

Execute a tool and return ServerResponse JSON envelope.

Parameters

server	Server handle.
tool_name	Tool name (without server prefix).
args_json	JSON string of arguments.

Returns: JSON string: {"result":"...","directives":[...]}. Caller must free with entropic_free(). Empty directives array when tool has no side effects.

Version: 1.8.5

Execute a tool and return ServerResponse JSON envelope.

Parameters

server	Server handle.
tool_name	Tool name.
args_json	JSON arguments.

Returns: Caller-owned ServerResponse JSON. @dg_internal

Version: 1.8.5

Definition at line 86 of file mcp_c_api.cpp.

◆ entropic_mcp_server_list_tools()

ENTROPIC_EXPORT char * entropic_mcp_server_list_tools ( entropic_mcp_server_t server )

List tools as JSON array string.

Parameters

server Server handle.

Returns: JSON string of tool definitions. Caller must free with entropic_free().

Version: 1.8.5

List tools as JSON array string.

Parameters

server Server handle.

Returns: Caller-owned JSON string. @dg_internal

Version: 1.8.5

Definition at line 70 of file mcp_c_api.cpp.

◆ entropic_mcp_server_name()

ENTROPIC_EXPORT const char * entropic_mcp_server_name ( entropic_mcp_server_t server )

Get the server name.

Parameters

server Server handle.

Returns: Null-terminated server name string. Owned by the server.

Version: 1.8.5

Get the server name.

Parameters

server Server handle.

Returns: Server name (server-owned). @dg_internal

Version: 1.8.5

Definition at line 56 of file mcp_c_api.cpp.

◆ entropic_mcp_server_set_working_dir()

ENTROPIC_EXPORT entropic_error_t entropic_mcp_server_set_working_dir	(	entropic_mcp_server_t	server,
		const char *	path
	)

Set the working directory for a server.

Parameters

server	Server handle.
path	Working directory path.

Returns: ENTROPIC_OK on success.

Version: 1.8.5

Base class default is no-op. Directory-aware servers (filesystem, bash, git) implement this. Enables ScopedSandbox (v2.1.5; formerly ScopedWorktree) to swap directories across .so boundaries without breaking isolation.

Set the working directory for a server.

Parameters

server	Server handle.
path	Working directory path.

Returns: ENTROPIC_OK on success. @dg_internal

Version: 1.8.5

Definition at line 126 of file mcp_c_api.cpp.

◆ entropic_plugin_api_version()

ENTROPIC_EXPORT int entropic_plugin_api_version ( void )

Report the plugin API version this plugin was built against.

Implemented BY THE PLUGIN, called by the engine's loader. Return ENTROPIC_MCP_PLUGIN_API_VERSION; a plugin reporting anything else is rejected with ENTROPIC_ERROR_PLUGIN_VERSION_MISMATCH and not registered.

Declared here (v2.10.1) rather than described only in prose so that plugin definitions pick up ENTROPIC_EXPORT from this header.

Returns: Plugin API version.

Version: 2.10.1

Report the plugin API version this plugin was built against.

Returns: Version number. @utility

Version: 1.8.2

Definition at line 603 of file inference_c_api.cpp.

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ ENTROPIC_MCP_PLUGIN_API_VERSION

Typedef Documentation

◆ entropic_mcp_server_t

Function Documentation

◆ entropic_create_server()

◆ entropic_free()

◆ entropic_mcp_server_configure()

◆ entropic_mcp_server_destroy()

◆ entropic_mcp_server_execute()

◆ entropic_mcp_server_list_tools()

◆ entropic_mcp_server_name()

◆ entropic_mcp_server_set_working_dir()

◆ entropic_plugin_api_version()