Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cubby.pro/llms.txt

Use this file to discover all available pages before exploring further.

​
Using Cubby with Claude

Cubby integrates with Claude Code and Claude Desktop through the Model Context Protocol (MCP). This lets you deploy and manage apps directly from your AI conversations.
This is the MCP path — an optional Claude-specific add-on, not the only way to use an AI agent with Cubby. The CLI path works in Claude, Codex, and Cursor equally and needs no MCP server. Start with Expert from paste for the agent-neutral flow; see Codex and Cursor for those tools. MCP just adds in-conversation deploy_app / get_logs / set_secret tools to Claude.

​
What’s MCP?

MCP (Model Context Protocol) is a standard way for AI assistants to interact with external tools. Cubby’s MCP server gives Claude the ability to:
  • Deploy apps to Cubby
  • Manage secrets
  • List your apps
  • View logs
  • Delete apps

​
Setup

The Cubby MCP server is published to npm as @cubby-pro/mcp. You can launch it on demand with npx -y @cubby-pro/mcp (no global install required). It runs as a local stdio MCP server, so your MCP client launches it on your machine and gives it access to your project directory.

​
Claude Code (project-local MCP)

Claude Code reads MCP servers from your project at .claude/settings.local.json (machine-local) or .claude/settings.json (committed/shared). cubby init scaffolds .claude/settings.local.json for you. To configure manually: 
{
  "mcpServers": {
    "cubby": {
      "command": "npx",
      "args": ["-y", "@cubby-pro/mcp"]
    }
  }
}
Reload the project (or restart Claude Code) after editing.

​
Claude Desktop (global MCP config)

Claude Desktop has a single global config file — not the same path as Claude Code:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "cubby": {
      "command": "npx",
      "args": ["-y", "@cubby-pro/mcp"]
    }
  }
}
Restart Claude Desktop after saving.
Use -y so npx does not prompt for a confirmation — MCP clients launch the server non-interactively.

​
Available Tools

The MCP server provides these tools to Claude:
ToolDescription
deploy_appDeploy an app from a local project directory (absolute path)
check_appValidate a local project before deploying
set_secretSet an environment variable
list_secretsList secrets for an app
list_appsList your deployed apps
get_logsView container logs
delete_appDelete a deployed app
whoamiShow the authenticated Cubby user
deploy_app is directory-only today. It needs an absolute path to a project directory on your local filesystem. There is no remote files or tarball_base64 upload mode — if Claude does not have local filesystem access, fall back to cubby deploy in your terminal.

​
Example Workflows

​
Build and Deploy

Ask Claude to build and deploy an app in a single conversation:
“Build a simple todo app with Prisma and deploy it to Cubby”
Claude will:
  1. Create the project structure
  2. Write the code
  3. Deploy using the deploy_app tool

​
Add a Secret

“Set my OpenAI API key as a secret for my todo-app”
Claude will:
  1. Ask you for the API key value
  2. Use set_secret to store it
  3. Tell you to redeploy for it to take effect

​
Check App Status

“Show me the logs for my todo-app”
Claude will use get_logs and format the output for you.

​
Authentication

The MCP server uses the same credentials as the CLI. If you’re logged into the CLI (cubby login), the MCP server will work automatically. If you haven’t logged in: 
cubby login

​
The CUBBY.md Context File

When Claude is building apps for Cubby, point it to the CUBBY.md file:
“Read CUBBY.md and follow its patterns when building this app”
This file contains:
  • Platform constraints
  • API route patterns (especially the async params for Next.js 16)
  • Authentication headers
  • What NOT to do (no auth libraries, etc.)

​
Example: Full Workflow

Here’s what a typical conversation might look like: You: Build a simple expense tracker app. Use Prisma for the database with an Expense model that has amount, description, and date fields. Deploy it to Cubby. Claude:
  1. Creates the project with cubby init
  2. Defines the Prisma schema
  3. Creates API routes for CRUD operations
  4. Builds a simple UI
  5. Uses deploy_app to deploy
  6. Returns the live URL
You: Add an OpenAI secret so the app can categorize expenses automatically. Claude:
  1. Asks you for your OpenAI API key
  2. Uses set_secret to store it
  3. Reminds you that a redeploy is needed
  4. Uses deploy_app to redeploy
You: Show me the last few logs from the app. Claude:
  1. Uses get_logs
  2. Formats and displays the logs

​
Tips

​
Be Specific

Tell Claude exactly what you want:
  • “Deploy this app to Cubby” - clear
  • “Put this online” - vague

​
Reference CUBBY.md

When starting a new app, tell Claude:
“This is a Cubby app. Read CUBBY.md for context.”

​
Redeploy After Secrets

Setting secrets doesn’t restart your app. After adding secrets:
“Redeploy the app so it picks up the new secret”

​
Troubleshooting

​
”Tool not available”

Make sure the MCP config is correct and Claude has been restarted.

​
”Not authenticated”

Run cubby login in your terminal. Claude Desktop launches the MCP server with a non-interactive shell and cannot finish a magic-link login on your behalf.

​
deploy_app returns NO_LOCAL_FS

Your MCP transport does not expose a local filesystem. Cubby’s MCP server only supports local stdio deploys today. Run cubby deploy from your terminal in the project directory instead.

​
Claude Desktop deploy fails

  • Pass an absolute project path to deploy_app (/Users/you/projects/my-app), not a relative path or ~.
  • Confirm you ran cubby login first.
  • Inspect Claude Desktop’s MCP logs for the underlying error before retrying.

​
”Deploy failed”

Ask Claude to run cubby check to see what’s wrong.