Skip to contents

console_tools() starts mcp-console serve and returns a named list of ellmer::ToolDef objects for all tools advertised by the server. Discovery does not require a tool named send. The tools share one server process and its persistent R, Python, and DuckDB state.

Usage

console_tools(
  config = load_console_config(project = project, path = path, version = version),
  ...,
  project = getwd(),
  path = NULL,
  version = NULL
)

Arguments

config

A ConsoleConfig(). By default, load_console_config() reads optional global/project files once and combines their settings. Pass ConsoleConfig() to skip files and use built-in defaults: host reads, private temporary writes, and no worker networking. Resolver defaults are independent. A supplied config never reads additional configuration files. The calling R installation is the default unless r.executable selects another installation. Explicit NULL is equivalent to ConsoleConfig(). Use the same path, version, and project when inspecting and launching a config.

...

Must be empty. Reserved for future use.

project

Existing directory to use as the child process's working directory, defaulting to getwd(). Relative config and runtime paths use this directory; the caller's working directory is unchanged.

path

NULL, or a path to an mcp-console executable.

version

NULL, or one published mcp-console version, such as "0.0.2".

Value

console_tools() returns a named list of ellmer::ToolDef objects to pass to an ellmer chat's $register_tools() method. Select a tool by name from the list for direct calls.

Details

Explicit NULL values are preserved where the server schema permits null. For send requirements, NULL package and constraint fields mean omission unless action = "set". Replacement declarations retain nullable values so explicit clears reach the server.

When the last tool is garbage collected, it closes the server's input to request shutdown and waits up to 15 seconds before forcibly stopping the server. With sandboxing enabled, the sandbox manager owns cleanup of worker descendants; the R wrapper's fallback targets only the server process. With ConsoleConfig(sandbox = FALSE), worker descendants may survive server shutdown.

See vignette("autonomous-report", package = "mcp.console") for an explicit configuration, permission edits, inspection, and an ellmer launch.

Result shape

Successful calls return an ellmer::ContentToolResult whose value holds the ordered text and image content. Its extra carries the server's result _meta and, under io.modelcontextprotocol/serverInfo, the identity the server reported in the handshake, which compatible chat UIs can use to attribute results. Errored results keep their existing unwrapped return shape.

Executable resolution

  • If path is supplied, console_tools() uses that executable directly.

  • Otherwise, if version is supplied, it resolves that published version with reticulate::uv_run_tool() without consulting PATH.

  • Otherwise, it uses mcp-console from PATH when available and falls back to the latest published version through reticulate::uv_run_tool().

path and version are mutually exclusive.

Examples

if (FALSE) { # \dontrun{
chat <- ellmer::chat_openai()
chat$register_tools(console_tools())
chat$chat(
  "Tell me something interesting about mtcars. Use the console as a workbench."
)

console_tools(path = Sys.which("mcp-console"))
console_tools(version = "0.0.2")
} # }