MCP Tools Reference: colaboratory.googleapis.com

Tool: execute_code

Runs Python in a Colab runtime's Jupyter kernel. Returns stdout, stderr, the value of the last expression (result), and any exception (executionError). Only text is returned, not images or plots. Output over the size limit is truncated and flagged with outputTruncated.

Set exactly one target:

  • session (runtimes/{runtime_id}/sessions/{session_id}) runs in that session's kernel, sharing variables and imports with its other calls. The session is created if it doesn't exist. Use this for anything stateful or multi-step.
  • runtime (runtimes/{runtime_id}) runs in a new session, which stays open. The result's session names it: reuse it, or close it with delete_session.

Calls to one session run one at a time, so parallel calls to it only queue and can time out. For parallel work, use a session per task and close each when it's done.

For code that may run long, pass a new UUID as executionId with a session target. A call is cut off after 600s with DEADLINE_EXCEEDED, but the code keeps running. After that, or if the call fails with UNAVAILABLE, repeat the identical call (same session and executionId). It reattaches and returns the output and result if the code had started, and otherwise runs it. Prefer this to running code in the background and polling it. Use a new UUID for each new execution, because once the result has been returned the same executionId runs the code again. Without an executionId, or with a runtime target, a timed-out execution can't be reattached, and a retry may run the code twice.

Cancelling a call (notifications/cancelled) interrupts whatever the session's kernel is running, which may be another call's code.

NOT_FOUND means the runtime doesn't exist, or has stopped. Find one with list_runtimes, and create one only if there's none. RESOURCE_EXHAUSTED (rate limit) means the code didn't run; retry with exponential backoff.

To move files between your machine and the runtime, use HTTP as described in get_runtime, not base64 through this tool, because the bytes fill your context. Files persist on the runtime across sessions.

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. A UUID that makes the execution resumable. Repeating the call with the same session and execution_id reattaches to the execution and returns its output instead of running the code again. Once the result has been returned, the same execution_id runs the code again.

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, in a new session that stays open. Format: runtimes/{runtime}.

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: ✅