MCP Tools Reference

Endpoint

GET /mcp returns 405 Method Not Allowed (Allow: POST).

Recommended request headers:

Authorization: Bearer <access-token>
Content-Type: application/json
Accept: application/json, text/event-stream

Missing or invalid token: the HTTP layer returns 401 before entering the MCP protocol.

For MCP clients that can only configure a server URL and cannot send custom headers, use http://<console-host>:8089/mcp?token=<access-token>. The query parameter name defaults to token and can be changed with CONSOLE_MCP_TOKEN_QUERY_PARAM. Prefer the header when available because URL tokens may appear in logs, browser history, or intermediaries; use HTTPS in production.

Supported MCP Methods

Tools at a Glance

All tool parameter schemas set additionalProperties: false. Passing an undefined field returns JSON-RPC error -32602 invalid params.

Tools listed in CONSOLE_HIDDEN_TOOLS are omitted from tools/list. They remain callable if the client already knows the tool name. See Console Configuration for details.

Tool names, titles, descriptions, and individual parameter descriptions can be overridden via environment variables (CONSOLE_MCP_TOOL_<TOOL>_NAME / _TITLE / _DESCRIPTION / _PARAM_<PARAM>_DESCRIPTION). The _NAME override changes the value clients see in tools/list and use as the routing key in tools/call; CONSOLE_HIDDEN_TOOLS still uses the internal capability ID. Setting a parameter description to an empty string hides that parameter from tools/list while still accepting it over HTTP — on such a schema additionalProperties becomes true. See Console Configuration.

Tool Reference

echo

Connectivity test. Verifies a worker is reachable.

Input:

Input example:

{ "message": "hello", "timeout_ms": 5000 }

Output:

Output example:

{ "message": "hello" }

pythonExec

Executes Python code on a worker and returns the result. Each call runs in an isolated environment with no persistent state.

Third-party dependencies: Runtime package installation (e.g. pip install) is not supported. The only way to use third-party packages is PEP 723 inline script metadata — declare a # /// script block at the top of your code and the worker will install the listed packages automatically before execution.

Input:

Input example:

{ "code": "print(1 + 1)", "timeout_ms": 60000 }

Input example with third-party dependencies (PEP 723):

{
  "code": "# /// script\n# dependencies = [\"httpx\"]\n# ///\nimport httpx\nprint(httpx.get('https://example.com').status_code)"
}

Output:

Output example:

{ "output": "2\n", "stderr": "", "exit_code": 0 }

A non-zero exit_code is returned as normal tool output, not a protocol-level error.

terminalExec

Executes a shell command inside a persistent terminal session, with state preserved across calls (working directory, environment variables, processes).

Input:

When create_if_missing=true, a session_id beginning with the reserved Computer Use prefix (CU: by default) is rejected. With create_if_missing=false, the same value is handled as an ordinary sandbox session lookup.

Input example:

{
  "command": "ls -la",
  "session_id": "sess_xxx",
  "create_if_missing": true,
  "lease_ttl_sec": 300,
  "timeout_ms": 30000
}

Output:

Output example:

{
  "session_id": "sess_xxx",
  "created": true,
  "stdout": "total 0\ndrwxr-xr-x ...\n",
  "stderr": "",
  "exit_code": 0,
  "stdout_truncated": false,
  "stderr_truncated": false,
  "lease_expires_unix_ms": 1770000000000
}

Concurrency and capacity errors:

• session_busy means the per-session concurrency limit has been reached.
• no_capacity means the worker-wide capability concurrency quota has been exhausted.
• session_capacity_exceeded means the selected worker has reached WORKER_TERMINAL_MAX_ACTIVE_SESSIONS while creating a new session; existing sessions remain usable.

These conditions are returned as MCP tool errors with isError: true, and the error text retains the corresponding error code. They are not JSON-RPC protocol-level errors.

computerUse

Lists or targets the calling account's worker-sys instances. A command is pinned to the selected real host machine and never falls back to another Worker. No session state is maintained.

Input:

Input example:

{
  "worker_id": "worker-id",
  "command": "screencapture -x /tmp/screenshot.png",
  "timeout_ms": 30000,
  "request_id": "req-001"
}

Output:

When worker_id is omitted, Console does not dispatch a command—even if command is also present—and returns every caller-owned online and offline Worker System:

{
  "worker_list": [
    { "worker_id": "worker-id", "node_name": "laptop", "status": "online", "capabilities": [] }
  ]
}

When worker_id is present, the execution output is:

Output example:

{
  "stdout": "",
  "stderr": "",
  "exit_code": 0,
  "stdout_truncated": false,
  "stderr_truncated": false
}

Key difference from terminalExec: no session-related fields (session_id, create_if_missing, created, lease_expires_unix_ms). Commands run directly on the selected host with no container isolation.

readImage

Reads an image file from a terminal session environment or a worker-sys host, returning it as an MCP image content item. Suitable for multimodal AI workflows.

Input:

Routing rules:

CU: is the default, case-sensitive prefix. It can be changed with the CONSOLE_COMPUTER_USE_SESSION_ID_PREFIX environment variable or the computer_use_session_id_prefix TOML setting; the examples below use the default. Changing the prefix alters how readImage, exportFile, and terminalExec interpret session IDs and is generally not recommended.

Input example (from a terminal session):

{ "session_id": "sess_xxx", "file_path": "/workspace/chart.png", "timeout_ms": 60000 }

Input example (from worker-sys host):

{ "session_id": "CU:worker-id", "file_path": "/tmp/screenshot.png", "timeout_ms": 10000 }

Output:

• If the file's MIME type is image/*: returns a MCP image content item (type: "image") containing base64-encoded image data.
• If the file's MIME type is not an image: returns a MCP text content item (type: "text") with the message:

unsupported mime type: <mime>; expected image/*

exportFile

Exports a file from a session to the console's configured S3-compatible object store and returns a presigned download URL.

Input:

Behavior:

• Available only when the console export object-store environment variables are configured.
• Upload/download presign TTLs are controlled by CONSOLE_EXPORT_FILE_UPLOAD_PRESIGN_TTL_SEC and CONSOLE_EXPORT_FILE_DOWNLOAD_PRESIGN_TTL_SEC.
• When session_id is CU:<worker_id>, routes to that caller-owned worker-sys readImage capability with action="export".
• Any other session_id routes to terminalResource with action="export" on the same worker that owns the terminal session.
• Terminal-session workers first probe the file, then export it from the session filesystem and upload it through a presigned HTTP PUT before the console returns a presigned download URL.
• Non-JSON probe failures inside the worker (for example OCI / docker exec startup failures) are surfaced as tool errors with docker exit code and output summary; they are not rewritten as JSON parse errors.

Input example:

{ "session_id": "sess_xxx", "file_path": "/workspace/report.png", "timeout_ms": 60000 }

Input example (from worker-sys host):

{ "session_id": "CU:worker-id", "file_path": "/tmp/report.png", "timeout_ms": 10000 }

Output:

Output fields depend on the CONSOLE_EXPORT_RETURN_SCHEMA environment variable:

Output example (ALL mode):

{ "signed_url": "https://objectstore.example.com/bucket/exports/...", "object_key": "exports/sess_xxx/abc-report.png", "filename": "report.png" }

Output example (SIGNED_URL mode):

{ "signed_url": "https://objectstore.example.com/bucket/exports/..." }

Output example (OBJECTKEY mode):

{ "object_key": "exports/sess_xxx/abc-report.png", "filename": "report.png" }

Common constraints:

• Unknown session returns a tool error such as session_not_found.
• This tool does not return file bytes inline.

Error Behavior

The former public alias computerUse is no longer special; clients must list/select a Worker and use its ID. Console still sends the unchanged internal session_id="computerUse" value to worker-sys.

See Also

• Console API Reference
• Security & FAQ