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'ssessionnames it: reuse it, or close it withdelete_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 |
| Fields | |
|---|---|
code |
Required. The Python source to execute. |
executionId |
Optional. A UUID that makes the execution resumable. Repeating the call with the same |
Union field
|
|
runtime |
The runtime to execute on, in a new session that stays open. Format: |
session |
The session to execute in. Format: |
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 ( |
| Fields | |
|---|---|
executionId |
The execution identifier this result is for, echoed from the request. Empty when the request supplied no |
session |
The session the execution ran in. Format: |
executionCount |
The Jupyter |
stdout |
Aggregated stdout across the execution. |
stderr |
Aggregated stderr across the execution. |
result |
The |
executionError |
Populated when the execution raised. Mutually exclusive with a successful completion. |
outputTruncated |
Whether the runtime truncated buffered output (size or line caps hit). When true, |
Error
| JSON representation |
|---|
{ "name": string, "value": string, "traceback": [ string ] } |
| Fields | |
|---|---|
name |
The exception class name, e.g. "NameError". |
value |
The exception message, e.g. "name 'foo' is not defined". |
traceback[] |
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: ✅