Tooling and Data APIs

This section covers tool declaration/execution APIs and shared data/property structures.

Tool APIs

Header File

components/mcp-c-sdk/include/esp_mcp_tool.h

Functions

esp_mcp_tool_t *esp_mcp_tool_create(const char *name, const char *description, esp_mcp_tool_callback_t callback)

Create a new MCP tool.

Parameters

name – [in] Tool name (must not be NULL)
description – [in] Tool description (must not be NULL)
callback – [in] Tool callback function (must not be NULL)

Returns

Pointer to the created tool, or NULL on failure

esp_mcp_tool_t *esp_mcp_tool_create_ex(const char *name, const char *title, const char *description, esp_mcp_tool_callback_ex_t callback)

Create a new MCP tool with extended callback.

Parameters

name – [in] Tool name
title – [in] Optional display title (can be NULL)
description – [in] Tool description
callback – [in] Extended callback

Returns

Pointer to tool or NULL

esp_err_t esp_mcp_tool_set_title(esp_mcp_tool_t *tool, const char *title)

Set tool title.

Parameters

tool – [in] Tool instance
title – [in] Tool title (nullable)

Returns

ESP_OK on success

esp_err_t esp_mcp_tool_set_icons_json(esp_mcp_tool_t *tool, const char *icons_json)

Set tool icons metadata JSON.

Parameters

tool – [in] Tool instance
icons_json – [in] JSON array/object string for icons (nullable)

Returns

ESP_OK on success

esp_err_t esp_mcp_tool_set_output_schema_json(esp_mcp_tool_t *tool, const char *schema_json)

Set tool output schema JSON.

Parameters

tool – [in] Tool instance
schema_json – [in] JSON schema object string (nullable)

Returns

ESP_OK on success

esp_err_t esp_mcp_tool_set_annotations_json(esp_mcp_tool_t *tool, const char *annotations_json)

Set tool annotations JSON.

Parameters

tool – [in] Tool instance
annotations_json – [in] JSON object string (nullable)

Returns

ESP_OK on success

esp_err_t esp_mcp_tool_set_task_support(esp_mcp_tool_t *tool, const char *task_support)

Set task support mode for the tool.

Parameters

tool – [in] Tool instance
task_support – [in] “required”, “optional”, or “forbidden”

Returns

ESP_OK on success

esp_mcp_tool_result_t *esp_mcp_tool_result_create(void)

Create tool result builder.

Returns: Tool result builder instance, or NULL on failure

esp_err_t esp_mcp_tool_result_destroy(esp_mcp_tool_result_t *result)

Destroy tool result builder.

Parameters: result – [in] Tool result builder
Returns: ESP_OK on success

esp_err_t esp_mcp_tool_result_set_is_error(esp_mcp_tool_result_t *result, bool is_error)

Set result isError flag.

Parameters

result – [in] Tool result builder
is_error – [in] True for application-level error

Returns

ESP_OK on success

esp_err_t esp_mcp_tool_result_add_text(esp_mcp_tool_result_t *result, const char *text)

Add text content block.

Parameters

result – [in] Tool result builder
text – [in] Text content

Returns

ESP_OK on success

esp_err_t esp_mcp_tool_result_add_image_base64(esp_mcp_tool_result_t *result, const char *mime_type, const char *base64_data)

Add base64 image content block.

Parameters

result – [in] Tool result builder
mime_type – [in] Image MIME type
base64_data – [in] Base64-encoded image payload

Returns

ESP_OK on success

esp_err_t esp_mcp_tool_result_add_audio_base64(esp_mcp_tool_result_t *result, const char *mime_type, const char *base64_data)

Add base64 audio content block.

Parameters

result – [in] Tool result builder
mime_type – [in] Audio MIME type
base64_data – [in] Base64-encoded audio payload

Returns

ESP_OK on success

esp_err_t esp_mcp_tool_result_add_resource_link(esp_mcp_tool_result_t *result, const char *uri, const char *name, const char *description, const char *mime_type)

Add resource_link content block.

Parameters

result – [in] Tool result builder
uri – [in] Resource URI
name – [in] Resource display name
description – [in] Resource description (nullable)
mime_type – [in] Resource MIME type (nullable)

Returns

ESP_OK on success

esp_err_t esp_mcp_tool_result_add_embedded_resource_text(esp_mcp_tool_result_t *result, const char *uri, const char *mime_type, const char *text)

Add embedded text resource content block.

Parameters

result – [in] Tool result builder
uri – [in] Resource URI
mime_type – [in] Resource MIME type
text – [in] Text payload

Returns

ESP_OK on success

esp_err_t esp_mcp_tool_result_add_embedded_resource_blob(esp_mcp_tool_result_t *result, const char *uri, const char *mime_type, const char *base64_blob)

Add embedded base64 blob resource content block.

Parameters

result – [in] Tool result builder
uri – [in] Resource URI
mime_type – [in] Resource MIME type
base64_blob – [in] Base64 blob payload

Returns

ESP_OK on success

esp_err_t esp_mcp_tool_result_set_structured_json(esp_mcp_tool_result_t *result, const char *structured_json_object)

Set structuredContent JSON object.

Parameters

result – [in] Tool result builder
structured_json_object – [in] JSON object string

Returns

ESP_OK on success

esp_err_t esp_mcp_tool_destroy(esp_mcp_tool_t *tool)

Destroy a tool.

Parameters

tool – [in] Pointer to the tool (must not be NULL)

Returns

ESP_OK if successful, otherwise an error code

ESP_ERR_INVALID_ARG: Invalid parameter
ESP_ERR_INVALID_STATE: Tool is not initialized
ESP_ERR_NO_MEM: Memory allocation failed
ESP_ERR_INTERNAL: Internal error

esp_err_t esp_mcp_tool_add_property(esp_mcp_tool_t *tool, esp_mcp_property_t *property)

Add a property to a tool.

Parameters

tool – [in] Pointer to the tool (must not be NULL)
property – [in] Pointer to the property (must not be NULL)

Returns

ESP_OK if successful, otherwise an error code

esp_err_t esp_mcp_tool_remove_property(esp_mcp_tool_t *tool, esp_mcp_property_t *property)

Remove a property from a tool.

Parameters

tool – [in] Pointer to the tool (must not be NULL)
property – [in] Pointer to the property (must not be NULL)

Returns

ESP_OK if successful, otherwise an error code

Type Definitions

typedef struct esp_mcp_tool_s esp_mcp_tool_t: MCP tool definition object.

typedef struct esp_mcp_tool_result_s esp_mcp_tool_result_t: Builder object for MCP tool call result payload.

typedef esp_mcp_value_t (*esp_mcp_tool_callback_t)(const esp_mcp_property_list_t *properties)

Tool callback function type.

Callback function called when a tool is executed. Receives the input properties and returns the execution result as a MCP value.

Param properties: [in] Tool input properties (can be NULL)
Return: MCP value containing the tool execution result

typedef esp_err_t (*esp_mcp_tool_callback_ex_t)(const esp_mcp_property_list_t *properties, esp_mcp_tool_result_t *result)

Extended tool callback allowing full MCP CallToolResult.

Implementations can populate a tool result with multiple content blocks, structuredContent, and isError flag.

Param properties: [in] Tool input properties (can be NULL)
Param result: [out] Tool result builder instance
Return: ESP_OK on success

Property APIs

Header File

components/mcp-c-sdk/include/esp_mcp_property.h

Functions

esp_mcp_property_t *esp_mcp_property_create(const char *name, esp_mcp_property_type_t type)

Create a MCP property.

Creates a new MCP property with the specified name and type.

Parameters

name – [in] Property name (must not be NULL)
type – [in] Property type

Returns

Pointer to the created property, or NULL on failure

esp_mcp_property_t *esp_mcp_property_create_with_bool(const char *name, bool default_value)

Create a MCP property with a default boolean value.

Parameters

name – [in] Property name (must not be NULL)
default_value – [in] Default boolean value

Returns

Pointer to the created property, or NULL on failure

esp_mcp_property_t *esp_mcp_property_create_with_int(const char *name, int default_value)

Create a MCP property with a default integer value.

Parameters

name – [in] Property name (must not be NULL)
default_value – [in] Default integer value

Returns

Pointer to the created property, or NULL on failure

esp_mcp_property_t *esp_mcp_property_create_with_float(const char *name, float default_value)

Create a MCP property with a default float value.

Parameters

name – [in] Property name (must not be NULL)
default_value – [in] Default float value

Returns

Pointer to the created property, or NULL on failure

esp_mcp_property_t *esp_mcp_property_create_with_string(const char *name, const char *default_value)

Create a MCP property with a default string value.

Parameters

name – [in] Property name (must not be NULL)
default_value – [in] Default string value (must not be NULL)

Returns

Pointer to the created property, or NULL on failure

esp_mcp_property_t *esp_mcp_property_create_with_array(const char *name, const char *default_value)

Create a MCP property with a default JSON array value.

Parameters

name – [in] Property name (must not be NULL)
default_value – [in] Default JSON array string (must be valid JSON, must not be NULL)

Returns

Pointer to the created property, or NULL on failure

esp_mcp_property_t *esp_mcp_property_create_with_object(const char *name, const char *default_value)

Create a MCP property with a default JSON object value.

Parameters

name – [in] Property name (must not be NULL)
default_value – [in] Default JSON object string (must be valid JSON, must not be NULL)

Returns

Pointer to the created property, or NULL on failure

esp_mcp_property_t *esp_mcp_property_create_with_range(const char *name, int min_value, int max_value)

Create a MCP property with a range constraint.

Creates an integer property with minimum and maximum value constraints.

Parameters

name – [in] Property name (must not be NULL)
min_value – [in] Minimum allowed value
max_value – [in] Maximum allowed value (must be >= min_value)

Returns

Pointer to the created property, or NULL on failure

esp_mcp_property_t *esp_mcp_property_create_with_int_and_range(const char *name, int default_value, int min_value, int max_value)

Create a MCP property with a default value and range constraint.

Creates an integer property with a default value and minimum/maximum constraints.

Parameters

name – [in] Property name (must not be NULL)
default_value – [in] Default integer value (must be within [min_value, max_value])
min_value – [in] Minimum allowed value
max_value – [in] Maximum allowed value (must be >= min_value)

Returns

Pointer to the created property, or NULL on failure

esp_err_t esp_mcp_property_destroy(esp_mcp_property_t *property)

Destroy a MCP property.

Frees all resources associated with the property.

Parameters

property – [in] Pointer to the property to destroy (must not be NULL)

Returns

ESP_OK: Property destroyed successfully
ESP_ERR_INVALID_ARG: Invalid parameter

bool esp_mcp_property_list_get_property_bool(const esp_mcp_property_list_t *list, const char *name)

Get a boolean property value from a property list.

Parameters

list – [in] Pointer to the property list (must not be NULL)
name – [in] Property name (must not be NULL)

Returns

Boolean value, or false if property not found or type mismatch

int esp_mcp_property_list_get_property_int(const esp_mcp_property_list_t *list, const char *name)

Get an integer property value from a property list.

Parameters

list – [in] Pointer to the property list (must not be NULL)
name – [in] Property name (must not be NULL)

Returns

Integer value, or 0 if property not found or type mismatch

float esp_mcp_property_list_get_property_float(const esp_mcp_property_list_t *list, const char *name)

Get a float property value from a property list.

Parameters

list – [in] Pointer to the property list (must not be NULL)
name – [in] Property name (must not be NULL)

Returns

Float value, or 0.0 if property not found or type mismatch

const char *esp_mcp_property_list_get_property_array(const esp_mcp_property_list_t *list, const char *name)

Get a JSON array property value from a property list.

Parameters

list – [in] Pointer to the property list (must not be NULL)
name – [in] Property name (must not be NULL)

Returns

Pointer to the JSON array string (internal pointer, do not free), or NULL if not found or type mismatch

const char *esp_mcp_property_list_get_property_object(const esp_mcp_property_list_t *list, const char *name)

Get a JSON object property value from a property list.

Parameters

list – [in] Pointer to the property list (must not be NULL)
name – [in] Property name (must not be NULL)

Returns

Pointer to the JSON object string (internal pointer, do not free), or NULL if not found or type mismatch

const char *esp_mcp_property_list_get_property_string(const esp_mcp_property_list_t *list, const char *name)

Get a string property value from a property list.

Parameters

list – [in] Pointer to the property list (must not be NULL)
name – [in] Property name (must not be NULL)

Returns

Pointer to the string value (internal pointer, do not free), or NULL if not found or type mismatch

Type Definitions

typedef enum esp_mcp_property_type_e esp_mcp_property_type_t

MCP property type enumeration.

Supported data types for MCP properties. Properties support boolean, integer, float, string, JSON array, and JSON object types.

typedef struct esp_mcp_property_s esp_mcp_property_t

MCP property structure.

Opaque structure representing a single MCP property with its name, type, and optional default value.

typedef struct esp_mcp_property_list_s esp_mcp_property_list_t

MCP property list structure.

Opaque structure representing a collection of MCP properties.

Enumerations

enum esp_mcp_property_type_e

MCP property type enumeration.

Supported data types for MCP properties. Properties support boolean, integer, float, string, JSON array, and JSON object types.

Values:

enumerator ESP_MCP_PROPERTY_TYPE_BOOLEAN: Boolean property type

enumerator ESP_MCP_PROPERTY_TYPE_INTEGER: Integer property type

enumerator ESP_MCP_PROPERTY_TYPE_FLOAT: Float property type

enumerator ESP_MCP_PROPERTY_TYPE_STRING: String property type

enumerator ESP_MCP_PROPERTY_TYPE_ARRAY: JSON array property type

enumerator ESP_MCP_PROPERTY_TYPE_OBJECT: JSON object property type

enumerator ESP_MCP_PROPERTY_TYPE_MAX: Maximum property type (reserved)

Data Value APIs

Header File

components/mcp-c-sdk/include/esp_mcp_data.h

Functions

esp_mcp_value_t esp_mcp_value_create_bool(bool value)

Create a MCP value with a boolean value.

Parameters: value – [in] Boolean value to store
Returns: MCP value structure with type ESP_MCP_VALUE_TYPE_BOOLEAN

esp_mcp_value_t esp_mcp_value_create_int(int value)

Create a MCP value with an integer value.

Parameters: value – [in] Integer value to store (signed 32-bit)
Returns: MCP value structure with type ESP_MCP_VALUE_TYPE_INTEGER

esp_mcp_value_t esp_mcp_value_create_float(float value)

Create a MCP value with a float value.

Parameters: value – [in] Floating-point value to store (32-bit)
Returns: MCP value structure with type ESP_MCP_VALUE_TYPE_FLOAT

esp_mcp_value_t esp_mcp_value_create_string(const char *value)

Create a MCP value with a string value.

Creates a copy of the input string. The string will be automatically freed when esp_mcp_value_destroy() is called.

Note

The input string is duplicated internally. The caller can safely free or modify the original string after this call.

Note

Always check if the returned type is ESP_MCP_VALUE_TYPE_INVALID before using.

Parameters

value – [in] Pointer to a null-terminated C string (must not be NULL)

Returns

MCP value structure:

type ESP_MCP_VALUE_TYPE_STRING: Success
type ESP_MCP_VALUE_TYPE_INVALID: value is NULL or memory allocation failed

esp_err_t esp_mcp_value_destroy(esp_mcp_value_t *value)

Destroy a MCP value.

Releases all resources associated with the MCP value, including dynamically allocated string memory for STRING type values.

Note

After calling this function, the value structure should not be used again.

Parameters

value – [inout] Pointer to the MCP value structure to destroy (must not be NULL)

Returns

ESP_OK: Value destroyed successfully
ESP_ERR_INVALID_ARG: Invalid parameter

Unions

union esp_mcp_value_data_t

#include <esp_mcp_data.h>

MCP value data union.

Union containing the actual data for MCP values. The active member is determined by the type field in the parent esp_mcp_value_t structure.

Note

Only access the member corresponding to the value type.

Public Members

bool bool_value: Boolean data value

int int_value: Integer data value (signed 32-bit)

float float_value: Floating-point data value (32-bit)

char *string_value: String data value (pointer to null-terminated C string)

Structures

struct esp_mcp_value_t

MCP value structure.

Complete MCP value with its type and associated data. Provides a unified way to handle different data types in the MCP protocol.

Note

The type field determines which member of the data union is valid.

Note

For STRING type, string_value points to dynamically allocated memory that will be freed by esp_mcp_value_destroy().

Public Members

esp_mcp_value_type_t type: Type of the value (boolean, integer, float, or string)

esp_mcp_value_data_t data: Union containing the actual value data

Enumerations

enum esp_mcp_value_type_t

MCP value type enumeration.

Supported data types for MCP values. Each type represents a different data representation that can be stored and transmitted.

Values:

enumerator ESP_MCP_VALUE_TYPE_INVALID: Invalid value (error state)

enumerator ESP_MCP_VALUE_TYPE_BOOLEAN: Boolean value

enumerator ESP_MCP_VALUE_TYPE_INTEGER: Integer value (signed 32-bit)

enumerator ESP_MCP_VALUE_TYPE_FLOAT: Floating-point value (32-bit)

enumerator ESP_MCP_VALUE_TYPE_STRING: String value (null-terminated)

Provide feedback about this document