Light Cloud AI: the MCP server

Light Cloud AI (LCAI) is the MCP server that makes your cloud AI-ready: an assistant can sign you up, create apps, deploy, manage databases and environments, pick a plan and add a card - the whole path from nothing to a running app, from a conversation. It is published on npm as @light-cloud/mcp-server and works with Claude Code, Claude Desktop, and GitHub Copilot in VS Code - or any other client that speaks MCP over stdio.

Requirements#

• Node.js 18 or later (the install commands below use npx, which ships with it).
• A Light Cloud account - or not. The connect tool creates one for an email that has none.

Install#

Claude Code#

Add the server with one command:

claude mcp add light-cloud -- npx @light-cloud/mcp-server

Verify it's connected:

claude mcp list

By default, Claude Code asks before each tool call. To approve the Light Cloud tools once, open /permissions and add mcp__light-cloud to the allow list - that covers every tool the server provides.

To remove the server later: claude mcp remove light-cloud.

Claude Desktop#

The quickest route is the desktop extension: download the latest light-cloud-<version>.mcpb from the releases page, double-click it, and Claude Desktop installs the server with everything it needs. No Node.js, no config file. Updates are the same file again; the extension keeps your sign-in.

Or add the server by hand to claude_desktop_config.json:

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

{
  "mcpServers": {
    "light-cloud": {
      "command": "npx",
      "args": ["@light-cloud/mcp-server"]
    }
  }
}

Restart Claude Desktop after saving. The Light Cloud tools appear under the tools icon in the chat input.

GitHub Copilot (VS Code)#

VS Code runs MCP servers for Copilot Chat's agent mode. Add the server to your project by creating .vscode/mcp.json:

{
  "servers": {
    "light-cloud": {
      "type": "stdio",
      "command": "npx",
      "args": ["@light-cloud/mcp-server"]
    }
  }
}

Or from a terminal:

code --add-mcp '{"name":"light-cloud","command":"npx","args":["@light-cloud/mcp-server"]}'

Save the file and pick Start above the server entry (VS Code may ask you to trust it first). For a user-wide install that applies to every workspace, run MCP: Add Server from the Command Palette and choose the Global target instead.

Then open Copilot Chat, switch to Agent mode, and check that the Light Cloud tools are ticked under Configure Tools. Copilot asks before running each tool; choose Always allow to skip the prompt for that tool next time.

To remove the server later, delete the entry from mcp.json.

Sign in (or sign up)#

Ask, with your email:

Connect me to Light Cloud as julia@example.com.

The connect tool answers with an 8-character code and the address console.light-cloud.com/device. Open it on any device - a phone is fine - sign in, type the code, approve. The assistant calls connect-status until the approval lands. No browser is needed on the machine running Claude, which is what makes this work over SSH, in containers and in Codespaces.

If the email has no account yet, the email we send carries a link: open it, type the code, and approving creates the account and a workspace on the free plan. No password is set until you choose one in the console; no password ever passes through the chat.

The older login tool - a browser tab on this machine with a loopback callback - still works.

Credentials are stored locally in ~/.lightcloud/credentials.json. The tools act as your signed-in user - they can do what you can do, nothing more. Check or end the session from the conversation, or sign a device out from Settings > Security > Connected devices in the console:

Am I logged in to Light Cloud?

Log me out of Light Cloud.

Deploy your first app#

From a local project#

Open Claude Code in your project directory (or Copilot Chat with the project open in VS Code, or Claude Desktop with the folder connected) and ask:

Deploy this project to Light Cloud.

The assistant asks at most two things before it touches anything, in one message: which workspace, if you belong to several, and whether the site should be public or behind a password. Then it packages the folder, uploads it, and deploys - see Deploy from an upload for what upload apps are. No Git remote required. It waits for the build and replies with the live URL on light-cloud.io (and the password, if you chose one), plus a link to the app in the console. Nothing else: no build settings to confirm, no plan to pick - the free plan is the default and a paid one is only raised if a tool refuses.

What it does not ask is what kind of project this is. The uploaded folder is read by the same detector the console uses for a connected repository, so an upload deploys exactly the way the same code would from GitHub: Next.js becomes a server app (or a static site when output: "export" is set), Vite and Create React App become static sites with the right output directory, a requirements.txt with FastAPI becomes a Python container on port 8000, a Dockerfile is used as-is with its EXPOSE port. The catalogue covers Next.js, Nuxt, SvelteKit, Remix, Astro, React, Vue, Angular, Svelte, SolidJS, Qwik, Gatsby, Docusaurus, Eleventy, Hugo, Jekyll, plain HTML, Express, Fastify, Hono, NestJS, AdonisJS, Django, Flask, FastAPI, Rails, Sinatra, Laravel, Symfony, WordPress, Spring Boot, Quarkus, Gin, Echo, Fiber, ASP.NET, Blazor, Wasp, and anything with a Dockerfile.

If the build fails, the reply says so and points at the environment logs; "why did it fail?" reads them and explains. A failure never takes down a version that was already live.

Behind a password#

Deploy this project to Light Cloud behind a password.

The site asks visitors for the password from its first request - the gate sits at the edge, in front of the app, so nothing is served without it. The assistant hands back the URL and the password together. Later:

Change the password on storefront to "spring-preview".

Make storefront public.

Use it for client previews, staging, or anything you want to share by link without publishing.

From a GitHub repository#

Create a Light Cloud app from my acme/storefront repo and deploy the main branch.

If your GitHub account isn't connected yet, Claude sends you the installation link for the Light Cloud GitHub App first, then creates the app and deploys the branch you asked for. From then on, every push deploys - the MCP server is how you set it up, not something in the path of your pushes.

Follow-up commands#

On the first deploy, a small .lightcloud config file is written to the project directory. It records which application the folder belongs to, so later requests need no arguments:

Redeploy.

What's the status of this app?

Show me the latest logs.

Everyday examples#

List my applications.

Create a staging environment for storefront and deploy the develop branch to it.

Why did the last deployment of storefront fail? Check the logs.

Delete the preview environment for storefront.

Claude combines tools on its own - asking "why did the deploy fail?" makes it look up the deployment, fetch the environment logs, and summarize what it finds.

Plan and payment#

Everything you would otherwise do under Billing in the console:

What plan is my workspace on, and how much of the pool is used?

Show me the plans. Put the workspace on Pro.

Add a card.

get-billing reads the plan, card and usage pool; list-plans and choose-plan change plan (the free plan needs no card). add-payment-method prints a Stripe-hosted link - open it anywhere, save the card, and payment-method-status picks it up; no card number is ever typed into the chat. When a paid plan is chosen without a card, the tool says so and names add-payment-method as the next step.

From nothing to running#

The server ships a prompt, deploy-from-scratch, that walks an assistant through the whole path in order: sign in or sign up, ask which workspace and whether the site should be public or password-protected, detect the framework, create the app from the repository or an upload, add a database and environment variables if the framework needs them, deploy, wait for the build, hand back the URL (and the password, if you chose one). In Claude Code, /light-cloud:deploy-from-scratch starts it.

Under the hood, upload-and-deploy and create-application take a password and answer with the URL, the console link and the environment id; wait-for-deployment blocks until the build is live and returns the URL, so the assistant is not polling status tables; set-password-protection changes or removes the gate. Every refusal a tool can return (a plan that lacks a size, an exhausted free pool, a missing card, a suspended workspace) carries a Next step: line, so the assistant calls that tool and retries rather than stopping. Tool results carry only what you can act on - the app's light-cloud.io URL, the console link, ids - never the infrastructure underneath.

What stays in the console#

Three things are deliberately not tools: changing the account password, two-factor settings, and the switch described next. Everything else the console can do, an assistant can do.

Turning agents off#

Settings → Security → Agents & CLI in the console decides what the CLI, the MCP server and the VS Code extension may do on your account. One master switch refuses every agent request; below it, groups you can keep console-only: creating and deploying, deleting, changing settings, databases, plan and payment, workspace and members, API keys. Reading is always allowed. Sign out all agents ends every agent session at once.

It is enforced on the backend from the session itself: a session issued to the CLI or an MCP server carries that in its token, fixed when it was created, so an agent cannot pass as the console by changing a header. The card can only be changed from a console session. When an assistant hits the switch it gets a refusal (AGENT_ACCESS_DISABLED or AGENT_ACTION_BLOCKED) that says where to change it, and it is told not to retry or look for another route.

API keys are separate: they are bound to a workspace, not a person, and are revoked under the workspace's API keys.

Tool reference#

You don't call tools directly - ask in plain language and the assistant picks the right ones. Each row gives the tool, what it does, and a prompt to copy that reaches it.

Account#

Deploy#

Apps and environments#

Logs and deployments#

Variables, databases, domains#

Plan and card#

Git providers#

Workspace, members, account#

Platform#

Prompt: deploy-from-scratch - in Claude Code, /light-cloud:deploy-from-scratch.

Use a different API endpoint#

The server talks to https://api.light-cloud.com by default. To point it at a staging or self-hosted API, set LIGHT_CLOUD_API_URL:

claude mcp add light-cloud --env LIGHT_CLOUD_API_URL=https://api.staging-light-cloud.com -- npx @light-cloud/mcp-server

Or in the Claude Desktop config:

{
  "mcpServers": {
    "light-cloud": {
      "command": "npx",
      "args": ["@light-cloud/mcp-server"],
      "env": {
        "LIGHT_CLOUD_API_URL": "https://api.staging-light-cloud.com"
      }
    }
  }
}

Troubleshooting#

• Tools don't show up. In Claude Code, run claude mcp list and check the server status. In Claude Desktop, make sure the config file is valid JSON and restart the app. In VS Code, open mcp.json, check the server shows Running, and make sure Copilot Chat is in Agent mode with the tools ticked under Configure Tools.
• Sign-in loops or expired session. Ask Claude to log out and connect again. As a hard reset, delete ~/.lightcloud/credentials.json and sign in fresh.
• "Device sign-in is not enabled". The environment the server points at has the code flow switched off; use the login tool (browser on this machine) instead.
• Wrong app targeted. The folder's .lightcloud file decides - ask Claude what this project's config says, or delete the file and deploy fresh.
• "Light Cloud storage refused the upload". A fault on our side, not your plan or permissions - the message says so. Deploy from a repository in the meantime and tell support; it is not something to fix in your project.
• The build failed. Ask "why did the build fail?" - the assistant reads the environment logs. The usual causes are a build command that needs a variable you have not set yet, or a Dockerfile that expects a file the folder does not have. A previously live version keeps serving.
• The site shows "Password required". That is the gate you asked for. The assistant printed the password with the URL; "make it public" removes the gate.
• The site returns 403 right after the deploy. The edge can reach the app a few seconds before it is fully wired up. Wait a moment and reload; if it persists past a minute, ask for the status.

Related#