mcp

The mcp namespace: 4 functions.

mcp/call

mcp.call(toolName, args?)

Call an MCP tool asynchronously. Returns a request ID to poll for the result. Use with task.await or manual polling via mcp.poll().

Parameters

• toolName string — Name of the MCP tool to call
• args table | string (optional) — Arguments for the tool. A table is converted to JSON with every value in it carried whole; a string in it longer than 16 MiB or holding bytes that are not UTF-8 text, a table in it holding more than 4096 keyed entries or 262144 sequence items, or a value nested more than 64 tables deep refuses the call, naming that argument, its size and the ceiling. A string is parsed as JSON as it stands; one that is not JSON refuses the call. A refused call answers mcp.poll with is_error and the reason, and the tool never runs

Returns string — Request ID for polling with mcp.poll()

mcp/image

mcp.image(source)

A picture to put in a tool result. Returns an image value — { type = "image", mime_type, data (base64), bytes, width, height, path? } — that can sit ANYWHERE in what a tool, a probe body or execute() returns, or in a notice's params: the caller receives each one as a picture beside the result's text, where the value itself stands as { type = "image", image = n } naming its position among the pictures. source is a VFS path to a PNG, JPEG, GIF or WebP file (relative paths resolve under /source/), a buffer holding one, or a table carrying it in base64 — an image value, or a capture result's imageBase64 (its path carries over). The size is read from the picture's header. Raises when the bytes are not one of those formats, or their header states no size. A result carries up to 16 pictures.

Parameters

• source string | buffer | table — VFS path, image bytes, or a table with base64 data / imageBase64

Returns { type: string, mime_type: string, data: string, bytes: number, width: number, height: number, path: string? } — The image value

return { verdict = "too dark", shot = mcp.image("/source/tmp/probe.png") }
local shot = tools.use("capture", "oneshot", { entity = e })
return { shot = mcp.image(shot) }

mcp/listTools

mcp.listTools()

List all available MCP tool names.

Returns {string} — Array of tool name strings

mcp/poll

mcp.poll(requestId)

Poll for a completed MCP tool call result. Returns nil if not yet complete.

Parameters

• requestId string — Request ID from mcp.call()

Returns { id: string, is_error: boolean, content: string } | nil — Result table with tool output, or nil if still pending