Prompt, Resource, and Completion APIs
This section covers prompt/resource definitions and completion provider interfaces.
Prompt APIs
Header File
Functions
-
esp_mcp_prompt_t *esp_mcp_prompt_create(const char *name, const char *title, const char *description, const char *messages_json, esp_mcp_prompt_render_cb_t render_cb, void *user_ctx)
Create an MCP prompt definition.
- Parameters
name – [in] Prompt name
title – [in] Optional prompt title (nullable)
description – [in] Optional prompt description (nullable)
messages_json – [in] Static messages JSON array string (nullable)
render_cb – [in] Optional render callback for dynamic prompt output
user_ctx – [in] User context passed to render callback
- Returns
Prompt instance on success, NULL on failure
-
esp_err_t esp_mcp_prompt_set_annotations(esp_mcp_prompt_t *prompt, const char *audience_json_array, double priority, const char *last_modified)
Set optional MCP prompt annotations.
- Parameters
prompt – Prompt instance
audience_json_array – JSON array string, e.g. [“assistant”,”user”]
priority – Priority [0,1], set <0 to keep unset
last_modified – ISO datetime string
-
esp_err_t esp_mcp_prompt_set_icons(esp_mcp_prompt_t *prompt, const char *icons_json)
Set prompt icons.
- Parameters
prompt – Prompt instance
icons_json – JSON object string for icons (nullable, set NULL to clear)
- Returns
ESP_OK on success
-
esp_err_t esp_mcp_prompt_destroy(esp_mcp_prompt_t *prompt)
Destroy an MCP prompt definition.
- Parameters
prompt – [in] Prompt instance
- Returns
ESP_OK on success
Type Definitions
-
typedef struct esp_mcp_prompt_s esp_mcp_prompt_t
MCP prompt definition object.
-
typedef esp_err_t (*esp_mcp_prompt_render_cb_t)(const char *arguments_json, char **out_description, char **out_messages_json, void *user_ctx)
Prompt render callback.
The callback should allocate output strings with malloc/calloc/strdup.
out_description can be NULL
out_messages_json must be a JSON array string when present
- Param arguments_json
[in] Prompt arguments as JSON object string (nullable)
- Param out_description
[out] Optional rendered description (allocated by callback)
- Param out_messages_json
[out] Rendered messages JSON array string (allocated by callback)
- Param user_ctx
[in] User context provided at prompt creation
- Return
ESP_OK on success
Resource APIs
Header File
Functions
-
esp_mcp_resource_t *esp_mcp_resource_create(const char *uri, const char *name, const char *title, const char *description, const char *mime_type, esp_mcp_resource_read_cb_t read_cb, void *user_ctx)
Create an MCP resource definition.
- Parameters
uri – [in] Resource URI
name – [in] Resource name
title – [in] Optional resource title (nullable)
description – [in] Optional resource description (nullable)
mime_type – [in] Default MIME type (nullable)
read_cb – [in] Optional callback to read resource content dynamically
user_ctx – [in] User context passed to read callback
- Returns
Resource instance on success, NULL on failure
-
esp_err_t esp_mcp_resource_set_annotations(esp_mcp_resource_t *resource, const char *audience_json_array, double priority, const char *last_modified)
Set optional MCP resource annotations.
- Parameters
resource – Resource instance
audience_json_array – JSON array string, e.g. [“assistant”,”user”]
priority – Priority [0,1], set <0 to keep unset
last_modified – ISO datetime string
-
esp_err_t esp_mcp_resource_set_size(esp_mcp_resource_t *resource, int64_t size)
Set resource size in bytes.
- Parameters
resource – Resource instance
size – Size in bytes (set negative to unset)
- Returns
ESP_OK on success
-
esp_err_t esp_mcp_resource_set_icons(esp_mcp_resource_t *resource, const char *icons_json)
Set resource icons.
- Parameters
resource – Resource instance
icons_json – JSON object string for icons (nullable, set NULL to clear)
- Returns
ESP_OK on success
-
esp_err_t esp_mcp_resource_destroy(esp_mcp_resource_t *resource)
Destroy an MCP resource definition.
- Parameters
resource – [in] Resource instance
- Returns
ESP_OK on success
Type Definitions
-
typedef struct esp_mcp_resource_s esp_mcp_resource_t
MCP resource definition object.
-
typedef esp_err_t (*esp_mcp_resource_read_cb_t)(const char *uri, char **out_mime_type, char **out_text, char **out_blob_base64, void *user_ctx)
Resource read callback.
The callback should allocate output strings with malloc/calloc/strdup. The framework will free them with free().
- Param uri
[in] Requested resource URI
- Param out_mime_type
[out] Output MIME type string (allocated by callback)
- Param out_text
[out] Output text payload (allocated by callback, nullable)
- Param out_blob_base64
[out] Output base64 payload (allocated by callback, nullable)
- Param user_ctx
[in] User context provided at resource creation
- Return
ESP_OK on success
Completion APIs
Header File
Functions
-
esp_mcp_completion_provider_t *esp_mcp_completion_provider_create(esp_mcp_completion_cb_t cb, void *user_ctx)
Create completion provider.
- Parameters
cb – [in] Completion callback
user_ctx – [in] User context for callback
- Returns
Completion provider instance on success, NULL on failure
-
esp_err_t esp_mcp_completion_provider_destroy(esp_mcp_completion_provider_t *provider)
Destroy completion provider.
- Parameters
provider – [in] Completion provider instance
- Returns
ESP_OK on success
Type Definitions
-
typedef struct esp_mcp_completion_provider_s esp_mcp_completion_provider_t
Completion provider object.
-
typedef esp_err_t (*esp_mcp_completion_cb_t)(const char *ref_type, const char *name_or_uri, const char *argument_name, const char *argument_value, const char *context_args_json, cJSON **out_result_obj, void *user_ctx)
Completion callback for completion/complete requests.
- Param ref_type
[in] Reference type (“ref/prompt” or “ref/resource”)
- Param name_or_uri
[in] Prompt name or resource URI
- Param argument_name
[in] Argument name being completed
- Param argument_value
[in] Partial argument value from client
- Param context_args_json
[in] JSON object string containing current arguments context (nullable)
- Param out_result_obj
[out] Output cJSON object with completion result
- Param user_ctx
[in] User context provided when provider was created
- Return
ESP_OK on success