Claude Code MCP Server

Create Claude Code cloud session

claude_create_cloud_session

Starts a Claude Code cloud session from a task description, cloning a GitHub repo or local directory first. Returns a session ID and URL, or a job ID to poll for the final result.

Instructions

Create a new Claude Code cloud session via claude --cloud on a pseudo-terminal (the CLI rejects this form when stdout is a pipe). The work runs as a background job and this call returns within a few seconds. If status is done, the result is final: the parsed session_id and session_url, or, when parsing fails, parsed false and the CLI output (terminal controls removed) in cli. Otherwise poll claude_get_session with job_id until job.status is done or the call returns an error; failures surface there with the same error codes. A github.com repo is cloned into CLAUDE_MCP_REPO_CACHE (origin set to that GitHub repository) and, when base_branch is set, checked out there before the CLI runs. Any other absolute directory must be on CLAUDE_MCP_REPOS. Omit repo to use CLAUDE_MCP_CWD. When Claude Code asks to trust the chosen folder, the call fails with WORKSPACE_NOT_TRUSTED unless CLAUDE_MCP_TRUST_CWD=1. The cloud VM's clone, push, and pull request use the Claude GitHub app (or /web-setup), not this server. If the session later can't push its branch to GitHub, ask it via claude_send_followup for a git format-patch (or full git diff) of its changes and apply, test, push and open the PR yourself.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "description": "<description>"
    },
    "name": "claude_create_cloud_session"
  }
}

Input Schema

Name	Required	Description
`repo`	No	Repository this session packages. A github.com owner/name or https://github.com/owner/name URL (any repository the Claude GitHub app can access; cloned into CLAUDE_MCP_REPO_CACHE), or an absolute directory on CLAUDE_MCP_REPOS. Omit to use CLAUDE_MCP_CWD.
`timeout_s`	No	Per-process time limit for this create's git steps and claude --cloud, in seconds. Omit to use CLAUDE_MCP_TIMEOUT_MS.
`base_branch`	No	Branch the cloud VM should clone, for a github.com repo. The cache checkout is moved to this branch before claude --cloud. Omit to use the remote's default branch. Not applied to a local directory.
`description`	Yes	Task description for the new cloud session.
`environment_id`	No	Cloud environment id (e.g. ccpool_...). Overrides CLAUDE_CLOUD_ENVIRONMENT_ID; omit to use that default.
`idle_timeout_s`	No	Stop claude --cloud when it prints nothing for this many seconds. Omit to use CLAUDE_MCP_IDLE_TIMEOUT_MS (off when unset).

Output Schema

Name	Required	Description
`cli`	Yes	CLI output with terminal control sequences removed. Until status is done, exit_code is null and stdout holds the last 4,000 characters so far.
`cwd`	Yes	Directory the CLI ran in.
`args`	Yes
`repo`	Yes	Normalized repository from the call, or null when the default directory was used.
`cache`	Yes	How the GitHub cache checkout was prepared. Null until it is ready, and for a local or default directory.
`title`	Yes
`job_id`	Yes	Background job for this create. Pass it to claude_get_session until status is done.
`parsed`	Yes	True when both session_id and session_url were parsed from CLI output.
`status`	Yes	cloning: preparing the GitHub cache checkout. starting: claude --cloud is running and has not printed a session yet. running: the session id was printed and the CLI has not exited. done: the CLI exited and the result below is final. cancelled: claude_cancel_session stopped the job; a session it already printed keeps running in the cloud.
`elapsed_ms`	Yes	Time since the job started, or its total duration once done.
`session_id`	Yes
`base_branch`	Yes	Branch the GitHub cache checkout was on, or null when no GitHub repository was selected.
`session_url`	Yes
`environment_id`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed13 schema fields changedv0.1.3Nov 6, 2026

addedInput schema / properties / base_branch

Added value: +{
+  "description": "Branch the cloud VM should clone, for a github.com repo. The cache checkout is moved to this branch before claude --cloud. Omit to use the remote's default branch. Not applied to a local directory.",
+  "maxLength": 255,
+  "minLength": 1,
+  "pattern": "^(?![-/])(?!HEAD$)(?!.*(?:\\.\\.|@\\{|\\/\\/|\\\\|\\s|~|\\^|:|\\?|\\*|\\[|\\.lock$|\\/$|\\.$))[A-Za-z0-9._/-]{1,255}$",
+  "type": "string"
+}

addedInput schema / properties / idle_timeout_s

Added value: +{
+  "description": "Stop claude --cloud when it prints nothing for this many seconds. Omit to use CLAUDE_MCP_IDLE_TIMEOUT_MS (off when unset).",
+  "maximum": 86400,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / repo

Added value: +{
+  "description": "Repository this session packages. A github.com owner/name or https://github.com/owner/name URL (any repository the Claude GitHub app can access; cloned into CLAUDE_MCP_REPO_CACHE), or an absolute directory on CLAUDE_MCP_REPOS. Omit to use CLAUDE_MCP_CWD.",
+  "maxLength": 4096,
+  "minLength": 1,
+  "pattern": "^(?:\\/[^\\0\\n\\r]+|[A-Za-z0-9][A-Za-z0-9._-]*\\/[A-Za-z0-9][A-Za-z0-9._-]*|https:\\/\\/(?:www\\.)?github\\.com\\/[A-Za-z0-9][A-Za-z0-9._-]*\\/[A-Za-z0-9][A-Za-z0-9._-]*(?:\\.git)?\\/?)$",
+  "type": "string"
+}

addedInput schema / properties / timeout_s

Added value: +{
+  "description": "Per-process time limit for this create's git steps and claude --cloud, in seconds. Omit to use CLAUDE_MCP_TIMEOUT_MS.",
+  "maximum": 86400,
+  "minimum": 1,
+  "type": "integer"
+}

addedOutput schema / properties / base_branch

Added value: +{
+  "description": "Branch the GitHub cache checkout was on, or null when no GitHub repository was selected.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / cache

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "cloned": {
+          "description": "True when this job made a fresh partial clone; false when it reused the existing cache with git fetch.",
+          "type": "boolean"
+        },
+        "duration_ms": {
+          "description": "Time spent on the clone or fetch, checkout and clean, not counting a wait for another job's lock.",
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "cloned",
+        "duration_ms"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "How the GitHub cache checkout was prepared. Null until it is ready, and for a local or default directory."
+}

changedOutput schema / properties / cli / description

Previous value: -"CLI output with terminal control sequences removed."New value: +"CLI output with terminal control sequences removed. Until status is done, exit_code is null and stdout holds the last 4,000 characters so far."

addedOutput schema / properties / cwd

Added value: +{
+  "description": "Directory the CLI ran in.",
+  "type": "string"
+}

addedOutput schema / properties / elapsed_ms

Added value: +{
+  "description": "Time since the job started, or its total duration once done.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

addedOutput schema / properties / job_id

Added value: +{
+  "description": "Background job for this create. Pass it to claude_get_session until status is done.",
+  "type": "string"
+}

addedOutput schema / properties / repo

Added value: +{
+  "description": "Normalized repository from the call, or null when the default directory was used.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / status

Added value: +{
+  "description": "cloning: preparing the GitHub cache checkout. starting: claude --cloud is running and has not printed a session yet. running: the session id was printed and the CLI has not exited. done: the CLI exited and the result below is final. cancelled: claude_cancel_session stopped the job; a session it already printed keeps running in the cloud.",
+  "enum": [
+    "cloning",
+    "starting",
+    "running",
+    "done",
+    "cancelled"
+  ],
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "session_id",
-  "session_url",
-  "title",
-  "parsed",
-  "environment_id",
-  "args",
-  "cli"
-]New value: +[
+  "job_id",
+  "status",
+  "elapsed_ms",
+  "session_id",
+  "session_url",
+  "title",
+  "parsed",
+  "environment_id",
+  "cwd",
+  "repo",
+  "base_branch",
+  "cache",
+  "args",
+  "cli"
+]

First observedv0.1.0Oct 21, 2026

TDQS

A4.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare this is a non-read-only, non-idempotent, open-world operation, and the description goes well beyond them: background job execution, few-second return, the WORKSPACE_NOT_TRUSTED failure code and the CLAUDE_MCP_TRUST_CWD=1 workaround, plus the parse-failure fallback returning `parsed` false with CLI output. That is substantial added context, but the description does not mention repeat-call cost (each call spins a new session, consistent with idempotentHint=false) or any rate/parallelism limits, so it stops short of the top band.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and the return/poll contract, then environment and repo mechanics, with no filler sentences. It is dense and somewhat overpacked for a single paragraph — the trailing git-format-patch recovery advice is troubleshooting prose rather than guidance for invoking this tool — but every sentence carries actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a six-parameter, open-world mutating tool: it covers the async job model, the success and failure shapes, the trust precondition, the repo/cache resolution rules, and the follow-up path. Since an output schema exists, the description is not obliged to enumerate return values, and the brief mention of `session_id`, `session_url`, `parsed`, and `cli` is bonus coverage rather than a gap-filler.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline would be 3, but the description adds meaning the schema does not: how `repo` values are actually consumed (cloned into CLAUDE_MCP_REPO_CACHE with origin set, or validated against CLAUDE_MCP_REPOS) and that `base_branch` moves the cache checkout before the CLI runs. It leaves `timeout_s`, `idle_timeout_s`, and `environment_id` entirely to the schema, which keeps it off a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a new Claude Code cloud session via `claude --cloud` on a pseudo-terminal') and immediately distinguishes itself from the local sibling by locating the work in a cloud VM. It also names claude_get_session as the follow-up poller, so an agent can separate this create call from the retrieval and cancel siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing: if `status` is `done` the result is final, otherwise poll claude_get_session with `job_id` until `job.status` is `done` or an error is returned. It also states the conditions that select each branch of `repo` (github.com clone vs. absolute dir on CLAUDE_MCP_REPOS vs. omit to use CLAUDE_MCP_CWD) and names the escalation path via claude_send_followup if the session cannot push.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server