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

#include <stddef.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
const char *	entropic_mcp_server_name (entropic_mcp_server_t server)
	Get the server name.

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

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_error_t	entropic_mcp_server_configure (entropic_mcp_server_t server, const char *config_json)
	Configure a server instance after creation.

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

void	entropic_mcp_server_destroy (entropic_mcp_server_t server)
	Destroy a server instance.

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. The ServerManager discovers plugins via dlopen and calls these functions through the opaque handle.

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.

Plugin export requirements: Every MCP server .so must export:
extern "C" ENTROPIC_EXPORT int entropic_plugin_api_version();

extern "C" ENTROPIC_EXPORT entropic_mcp_server_t entropic_create_server();

entropic_mcp_server_t
struct entropic_mcp_server * entropic_mcp_server_t
Opaque handle to an MCP server instance.
Definition i_mcp_server.h:50

entropic_plugin_api_version
ENTROPIC_EXPORT int entropic_plugin_api_version()
Plugin API version.
Definition inference_c_api.cpp:407

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).

Version: 1.8.5

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 237 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 50 of file i_mcp_server.h.

Function Documentation

◆ entropic_free()

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().

@utility

Version: 1.8.0

Definition at line 1738 of file entropic.cpp.

◆ entropic_mcp_server_configure()

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.

Definition at line 107 of file mcp_c_api.cpp.

◆ entropic_mcp_server_destroy()

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.

Definition at line 142 of file mcp_c_api.cpp.

◆ entropic_mcp_server_execute()

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.

Definition at line 86 of file mcp_c_api.cpp.

◆ entropic_mcp_server_list_tools()

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.

Definition at line 70 of file mcp_c_api.cpp.

◆ entropic_mcp_server_name()

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).

Definition at line 56 of file mcp_c_api.cpp.

◆ entropic_mcp_server_set_working_dir()

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.

Definition at line 126 of file mcp_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_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()