MCP Server API

Files
file	mcp_server.h
	Model Context Protocol (MCP) Server API.

Data Structures
struct	mcp_tool_metadata
	Tool metadata structure. More...
struct	mcp_tool_record
	Tool definition structure. More...
struct	mcp_tool_message
	Message sent from a tool (response/notification). More...

Typedefs
typedef void *	mcp_server_ctx_t
	Server context handle.
typedef int(*	mcp_tool_callback_t) (enum mcp_tool_event_type event, const char *arguments, const char *execution_token)
	Tool callback function.

Enumerations
enum	mcp_tool_msg_type { MCP_USR_TOOL_RESPONSE , MCP_USR_TOOL_NOTIFICATION , MCP_USR_TOOL_CANCEL_ACK , MCP_USR_TOOL_PING }
	MCP Tool message type. More...
enum	mcp_tool_event_type { MCP_TOOL_CALL_REQUEST , MCP_TOOL_CANCEL_REQUEST }
	MCP Tool event type. More...

Functions
mcp_server_ctx_t	mcp_server_init (void)
	Initialize the MCP Server.
int	mcp_server_start (mcp_server_ctx_t server_ctx)
	Start the MCP Server.
int	mcp_server_submit_tool_message (mcp_server_ctx_t server_ctx, const struct mcp_tool_message *user_msg, const char *execution_token)
	Submit a message from a tool (response/notification).
int	mcp_server_add_tool (mcp_server_ctx_t server_ctx, const struct mcp_tool_record *tool_record)
	Add a tool to the server.
int	mcp_server_remove_tool (mcp_server_ctx_t server_ctx, const char *tool_name)
	Remove a tool from the server.
int	mcp_server_is_execution_canceled (mcp_server_ctx_t server_ctx, const char *execution_token, bool *is_canceled)
	Helper for checking the execution state of a tool.

Detailed Description

Since

4.5

Version

0.1.0

Typedef Documentation

mcp_server_ctx_t

typedef void* mcp_server_ctx_t

#include <zephyr/net/mcp/mcp_server.h>

Server context handle.

mcp_tool_callback_t

typedef int(* mcp_tool_callback_t) (enum mcp_tool_event_type event, const char *arguments, const char *execution_token)

#include <zephyr/net/mcp/mcp_server.h>

Tool callback function.

Parameters

event	Type of tool event (call or cancel request)
arguments	JSON string with tool parameters
execution_token	Unique execution identifier (UUID string)

Note

This callback is executed in the context of an MCP request worker thread. The default worker thread stack size is CONFIG_MCP_REQUEST_WORKER_STACK_SIZE. If your tool callback requires more stack space increase this value.

Consider using heap allocation for large buffers to minimize stack usage.

This callback blocks an MCP server worker thread. For long-running operations, it is recommended to use your own thread pool to execute the work asynchronously and return quickly from this callback to avoid blocking the MCP server worker thread and potentially degrading server responsiveness.

It is up to the user application whether it allows concurrent executions of the same tool or not.

Returns

0 on success, negative errno on failure

Enumeration Type Documentation

mcp_tool_event_type

enum mcp_tool_event_type

#include <zephyr/net/mcp/mcp_server.h>

MCP Tool event type.

Enumerator
MCP_TOOL_CALL_REQUEST	JSON-RPC request calling the tool.
MCP_TOOL_CANCEL_REQUEST	Tool cancellation request.

mcp_tool_msg_type

enum mcp_tool_msg_type

#include <zephyr/net/mcp/mcp_server.h>

MCP Tool message type.

Enumerator
MCP_USR_TOOL_RESPONSE	JSON-RPC response to a client request.
MCP_USR_TOOL_NOTIFICATION	Tool to client notification.
MCP_USR_TOOL_CANCEL_ACK	Cancellation acknowledgment to the MCP Core.
MCP_USR_TOOL_PING	Ping to signify the tool is alive to the MCP Core.

Function Documentation

mcp_server_add_tool()

int mcp_server_add_tool	(	mcp_server_ctx_t	server_ctx,
		const struct mcp_tool_record *	tool_record )

#include <zephyr/net/mcp/mcp_server.h>

Add a tool to the server.

Parameters

server_ctx	Server context handle
tool_record	Tool definition with metadata and callback

Returns

0 on success, negative errno on failure

Return values

-EINVAL	Invalid tool_record
-EEXIST	Tool name already exists
-ENOSPC	Registry full

mcp_server_init()

mcp_server_ctx_t mcp_server_init

(

void

)

#include <zephyr/net/mcp/mcp_server.h>

Initialize the MCP Server.

Returns

mcp_server_ctx_t on success, NULL on failure

mcp_server_is_execution_canceled()

int mcp_server_is_execution_canceled	(	mcp_server_ctx_t	server_ctx,
		const char *	execution_token,
		bool *	is_canceled )

#include <zephyr/net/mcp/mcp_server.h>

Helper for checking the execution state of a tool.

Note

Alternative way of checking the cancellation. Primary check should be through the tool call event (struct mcp_tool_event_type). This checker needs to use mutexes and linear search to locate the required execution context.

Parameters

server_ctx	Server context handle
execution_token	Token representing the execution (UUID string)
is_canceled	Pointer to store cancellation state

Returns

0 on success, negative errno on failure

Return values

-EINVAL	Invalid tool name
-ENOENT	Tool not found

mcp_server_remove_tool()

int mcp_server_remove_tool	(	mcp_server_ctx_t	server_ctx,
		const char *	tool_name )

#include <zephyr/net/mcp/mcp_server.h>

Remove a tool from the server.

Note

Should be called again if it returns -EBUSY, which signifies that the tool is currently being executed.

Parameters

server_ctx	Server context handle
tool_name	Name of tool to remove

Returns

0 on success, negative errno on failure

Return values

-EINVAL	Invalid tool name
-ENOENT	Tool not found
-EBUSY	Tool is being executed and can't be removed (try again later)

mcp_server_start()

int mcp_server_start

(

mcp_server_ctx_t

server_ctx

)

#include <zephyr/net/mcp/mcp_server.h>

Start the MCP Server.

Parameters

server_ctx

Server context handle

Returns

0 on success, negative errno on failure

mcp_server_submit_tool_message()

int mcp_server_submit_tool_message	(	mcp_server_ctx_t	server_ctx,
		const struct mcp_tool_message *	user_msg,
		const char *	execution_token )

#include <zephyr/net/mcp/mcp_server.h>

Submit a message from a tool (response/notification).

Parameters

server_ctx	Server context handle
user_msg	Application message to submit
execution_token	Execution token for tracking (UUID string)

Returns

0 on success, negative errno on failure