CloudShell Overview and Setup

Insites CloudShell connects Claude AI to your Insites instance. Once set up, you can have a conversation with Claude, and it will take action on your instance - deploying files, fetching logs, managing environment variables - without you ever needing to open a terminal or run a command.

CloudShell uses the Model Context Protocol (MCP), an open standard that enables AI assistants like Claude to interact securely with external tools and services.

What You Can Do

• Deploy files - Push one or more files to your instance with automatic batching
• Sync files - Instantly sync a single file during development
• Fetch logs - View recent instance logs to diagnose issues
• Manage environment variables - Add, update, or view environment variables on your instance

CloudShell works with both Claude Desktop (the standalone app) and Claude Code (the VS Code extension).

Prerequisites

Before starting, make sure you have the following:

• A computer running macOS or Windows
• An Insites Console account with access to at least one instance
• Your Insites Console login email and password
• Your instance UUID (found in the Insites Console under Instance Details)
• Your instance URL (found in the Insites Console under Instance Details)
• Claude Desktop or Claude Code (VS Code extension) installed
• Node.js 18 or higher installed - download from nodejs.org (LTS version recommended)

Finding Your Instance UUID and URL

Log in to the Insites Console, select your instance from the list, then click Instance Details and the General tab. Your UUID is the long string in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Your instance URL is listed as the instance domain (for example, https://your-instance.insites.site).

Verifying Node.js

Open a terminal (macOS: Terminal app) or Command Prompt (Windows: search for cmd in the Start menu) and run:

node -v

You should see a version number such as v18.17.0 or higher.

Setup: Claude Desktop

Claude Desktop stores its connection settings in a file called claude_desktop_config.json. The easiest way to open it is through the Claude Desktop interface.

Step 1: Open the Config File

• macOS: Click Claude in the menu bar, then Settings, then Developer, then Edit Config
• Windows: Click File, then Settings, then Developer, then Edit Config

If you cannot find it through the menu, you can open the file manually:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Step 2: Add the CloudShell Connection

Add an insites-cloudshell entry to the mcpServers section of your config file using the values below. Replace the placeholder values with your own credentials.

The following headers must be included as arguments. Each header is passed as a separate --header argument:

The full configuration uses the mcp-remote npm package to connect. The args array should contain: mcp-remote, the CloudShell URL, --transport, http-first, followed by each header pair as --header and x-insites-*:VALUE.

If your config file already contains other MCP server entries, add the insites-cloudshell block inside the existing mcpServers section, separated from the previous entry by a comma.

Step 3: Restart Claude Desktop

Your changes take effect only after a full restart. Closing the window is not sufficient - you must fully quit the application.

• macOS: Press Cmd + Q, or right-click the Claude icon in the Dock and choose Quit. Then reopen Claude Desktop.
• Windows: Click File then Exit, or right-click the Claude icon in the system tray and choose Quit. Then reopen Claude Desktop.

Setup: Claude Code (VS Code Extension)

Claude Code uses a different config mechanism than Claude Desktop. There are two approaches, depending on whether you are setting it up for yourself or your whole team.

Option A: Individual Setup

Run this command in your terminal. Replace the placeholder values with your credentials.

macOS:

claude mcp add -s user insites-cloudshell 
  -- /opt/homebrew/bin/npx mcp-remote 
  https://cloudshell.insites.io/mcp 
  --transport http-only 
  --header x-insites-email:YOUR_EMAIL 
  --header x-insites-instance:YOUR_INSTANCE_UUID 
  --header x-insites-password:YOUR_PASSWORD 
  --header x-insites-url:YOUR_INSTANCE_URL

Windows:

claude mcp add -s user insites-cloudshell ^
  -- npx mcp-remote ^
  https://cloudshell.insites.io/mcp ^
  --transport http-only ^
  --header x-insites-email:YOUR_EMAIL ^
  --header x-insites-instance:YOUR_INSTANCE_UUID ^
  --header x-insites-password:YOUR_PASSWORD ^
  --header x-insites-url:YOUR_INSTANCE_URL

This stores the config globally in ~/.claude.json, so it is available in every project automatically. Restart VS Code after running the command.

Verify the connection by running:

claude mcp get insites-cloudshell

You should see Status: Connected.

Option B: Team / Project Setup

This approach stores the config in the project directory, so your whole team gets it automatically when they open the project.

Step 1: Create .mcp.json in your project root with the same configuration structure used for Claude Desktop, but set the transport to http-only instead of http-first.

The .mcp.json file follows the same mcpServers format as the Claude Desktop config shown above. Use npx as the command (without the full path) for cross-platform compatibility.

Important: Never commit real credentials. Either add .mcp.json to your .gitignore, or commit a template version with placeholder values and have each developer fill in their own copy locally.

Step 2: Create .claude/settings.json in your project root with an enabledMcpjsonServers array containing insites-cloudshell. This tells Claude Code to automatically trust and load the server without prompting each developer for approval.

Without this file, Claude Code will show a trust dialog the first time each developer opens the project. If that dialog is dismissed, the server is silently skipped on every subsequent restart.

Step 3: Each team member should restart VS Code once after pulling the new files.

Verifying the Connection

Once Claude Desktop or Claude Code has restarted, confirm that CloudShell is connected:

1. Start a new conversation
2. Look for a hammer icon near the bottom of the message input area - this indicates MCP tools are active
3. Click the hammer icon to see the available tools. You should see insites_deploy, insites_sync_file, insites_get_logs, insites_env_add, and insites_env_get listed
4. Send this test message to confirm everything is working: List the environment variables on my Insites instance

If Claude responds with a list of your instance environment variables, the connection is working correctly.

Security

Your Insites credentials (email, password, and instance UUID) are stored in the config file on your local computer. This file is not shared with Insites or Anthropic. Treat this file like any sensitive configuration file - do not share its contents with others and do not commit it to a public repository.