MCP Tools Reference: colaboratory.googleapis.com

Tool: create_session

Opens a Jupyter kernel session on a Colab runtime, identified by its resource name (runtimes/{runtime_id}).

Sessions group subsequent execute_code calls so they share kernel state (variables, imports, etc.).

An optional session_id may be supplied. If omitted, the server generates a random UUID. If supplied, session_id must be 1-63 characters, contain only lowercase ASCII letters, digits, and hyphens, start with a letter, and end with a letter or digit (RFC 1034). Returns the new session as runtimes/{runtime_id}/sessions/{session_id}.

The session lives until the runtime is deleted or the session is closed via delete_session. Abandoned sessions hold kernel memory.

The following code sample shows how to use curl to call the create_session 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": "create_session",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

Request message for CreateSession.

CreateSessionRequest

JSON representation 
{
  "parent": string,
  "sessionId": string,
  "session": {
    object (Session)
  }
}
Fields
parent

string

Required. The runtime on which to open the session. Format: runtimes/{runtime}.
sessionId

string

Optional. Identifier for the session, unique within the parent runtime. If unset, the server generates a random UUID. Resource-name uniqueness is scoped to the runtime, not globally; in other words, two different runtimes can each host a session with the same session_id.

CreateSession has create-or-get semantics on session_id: if a session with the given ID is already open on the runtime, the existing session is returned unchanged (no new session is created, no error is returned). This matches Jupyter's underlying deduplication behavior and means callers can safely retry CreateSession with the same session_id to recover from transient failures without first checking whether the session exists.

See https://google.aip.dev/122#resource-id-segments, https://google.aip.dev/133#user-specified-ids and https://datatracker.ietf.org/doc/html/rfc1034 for conformance rules. Summarized, they are:

  • 1 to 63 characters
  • Lower case letters, digits, and hyphens
  • Start with a letter
  • End with a letter or digit
session

object (Session)

Optional. The session to create. All fields are currently OUTPUT_ONLY and the server ignores any caller-supplied values; the field exists for AIP-133 compliance and forward compatibility with future caller-settable session attributes.

Session

JSON representation 
{
  "name": string
}
Fields
name

string

Identifier. The name of the session in the format runtimes/{runtime}/sessions/{session}, where session is either the value supplied via CreateSessionRequest.session_id or, if unset, a random UUID generated by the server.

Output Schema

A Jupyter kernel session attached to a Colab runtime.

Sessions are not persisted across runtime lifecycles: when the parent runtime is deleted (see google.colab.v1beta.ColabService.DeleteRuntime), all of its sessions are implicitly closed.

Session

JSON representation 
{
  "name": string
}
Fields
name

string

Identifier. The name of the session in the format runtimes/{runtime}/sessions/{session}, where session is either the value supplied via CreateSessionRequest.session_id or, if unset, a random UUID generated by the server.

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