MCP Tools Reference: colaboratory.googleapis.com

Tool: execute_code

Executes Python in a Colab runtime's Jupyter kernel and returns the captured stdout, stderr, the last expression's value, and any error.

Target exactly one of runtime (runtimes/{runtime_id}), which runs in a fresh kernel session, or session (runtimes/{runtime_id}/sessions/{session_id}), which runs in that session and shares kernel state (variables, imports, loaded data) with its other calls. A session is created if it does not already exist.

stdout and stderr stream incrementally as progress notifications and are also returned aggregated in the result.

To make an execution resumable, pass a stable executionId (a UUID). A call that outlives the streaming deadline (600s) ends with a DEADLINE_EXCEEDED error before returning a result. To recover, re-issue the identical call with the same executionId to reattach and keep streaming through to the final result. Reattaching works only until the result is returned. Reusing the same executionId after that starts a new execution. Without an executionId, an execution that outlives the deadline keeps running but cannot be reconnected to.

Clients use the standard MCP notifications/cancelled flow on an in-flight execution. When cancelled, interrupts the kernel.

Only text is returned. Rich outputs (images, plots, widgets) are not returned. Oversized output is truncated and flagged via outputTruncated. Files written to disk persist on the runtime regardless of session.

The following code sample shows how to use curl to call the execute_code MCP tool.

Curl Request 
curl --location 'https://colaboratory.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "execute_code",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

Request message for ExecuteCode.

ExecuteCodeRequest

JSON representation 
{
  "code": string,
  "executionId": string,

  // Union field target can be only one of the following:
  "runtime": string,
  "session": string
  // End of list of possible types for union field target.
}
Fields
code

string

Required. The Python source to execute.
executionId

string

Optional. An optional client-supplied execution identifier (a UUID). Supply one to make the execution resumable: re-issuing ExecuteCode with the same execution_id reattaches to the original execution and replays its output rather than starting a new one. Reattaching also requires targeting the same session: a runtime target opens a new session each call, leaving the buffered execution unaddressable. If omitted, the execution is not buffered and cannot be resumed (it still streams, and returns its result if it finishes within the deadline).

Once a request carrying an execution_id streams the final response carrying the ExecuteCodeResult, the output is freed and subsequent requests with the same execution_id will start a new execution.

Union field target. Where to execute. Exactly one of runtime or session must be set:

  • runtime: execute in a fresh session created on this runtime.
  • session: execute in this session, sharing kernel state (variables, imports, etc.) with other executions in the same session. The session is created if it does not already exist (create-or-get). The runtime is derived from the session name. target can be only one of the following:
runtime

string

The runtime to execute on. Format: runtimes/{runtime}.

Each call opens a fresh kernel session, so an execution run this way can only be resumed by targeting the session (returned in the result).
session

string

The session to execute in. Format: runtimes/{runtime}/sessions/{session}.

Output Schema

The result of an ExecuteCode call, returned as the terminal structured_content of the response stream.

ExecuteCodeResult

JSON representation 
{
  "executionId": string,
  "session": string,
  "executionCount": integer,
  "stdout": string,
  "stderr": string,
  "result": string,
  "executionError": {
    object (Error)
  },
  "outputTruncated": boolean
}
Fields
executionId

string

The execution identifier this result is for, echoed from the request. Empty when the request supplied no execution_id (such an execution is not resumable). Use it to resume.
session

string

The session the execution ran in. Format: runtimes/{runtime}/sessions/{session}.
executionCount

integer

The Jupyter In[N] execution count assigned by the kernel. Informational only. Not for addressing executions, for that use execution_id.
stdout

string

Aggregated stdout across the execution.
stderr

string

Aggregated stderr across the execution.
result

string

The text/plain representation of the last expression's value, if the execution ended on an expression. Empty otherwise.
executionError

object (Error)

Populated when the execution raised. Mutually exclusive with a successful completion.
outputTruncated

boolean

Whether the runtime truncated buffered output (size or line caps hit). When true, stdout/stderr are tail-truncated.

Error

JSON representation 
{
  "name": string,
  "value": string,
  "traceback": [
    string
  ]
}
Fields
name

string

The exception class name, e.g. "NameError".
value

string

The exception message, e.g. "name 'foo' is not defined".
traceback[]

string

The formatted traceback, one frame per entry.

Tool Annotations

Tool annotations are sent to MCP clients to describe the basic risk of a given tool. Most clients treat these hints as untrusted, but they can be used to decide when a confirmation prompt might be sent to a user.

Along with the title string, the following boolean hints are defined as follows:

  • readOnlyHint: If true, the tool doesn't modify its environment. Default: false.
  • destructiveHint: If true, then the tool can perform destructive actions. If false, then the tool can only perform additive actions. Default: true.
  • idempotentHint: If true, then calling the tool repeatedly with the same arguments will have no additional effect on its environment. Default: false.
  • openWorldHint: If true, then the tool can interact with an 'open world' of external entities. If false, then the tool can only interact with internal entities. For example, a web search tool would be open world, while a memory tool would not be open world.

Destructive Hint: ✅ | Idempotent Hint: ❌ | Read Only Hint: ❌ | Open World Hint: ✅