> ## 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

> Deploy apps directly from AI conversations

# 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.

<Info>
  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](/tutorials/expert-from-paste) for the
  agent-neutral flow; see [Codex](/tutorials/using-with-codex) and
  [Cursor](/tutorials/using-with-cursor) for those tools. MCP just adds in-conversation
  `deploy_app` / `get_logs` / `set_secret` tools to Claude.
</Info>

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

```json theme={null}
{
  "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`

```json theme={null}
{
  "mcpServers": {
    "cubby": {
      "command": "npx",
      "args": ["-y", "@cubby-pro/mcp"]
    }
  }
}
```

Restart Claude Desktop after saving.

<Note>
  Use `-y` so `npx` does not prompt for a confirmation -- MCP clients launch the server non-interactively.
</Note>

## Available Tools

The MCP server provides these tools to Claude:

| Tool           | Description                                                  |
| -------------- | ------------------------------------------------------------ |
| `deploy_app`   | Deploy an app from a local project directory (absolute path) |
| `check_app`    | Validate a local project before deploying                    |
| `set_secret`   | Set an environment variable                                  |
| `list_secrets` | List secrets for an app                                      |
| `list_apps`    | List your deployed apps                                      |
| `get_logs`     | View container logs                                          |
| `delete_app`   | Delete a deployed app                                        |
| `whoami`       | Show the authenticated Cubby user                            |

<Warning>
  `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.
</Warning>

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

```bash theme={null}
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.

## Related

* [Expert from paste](/tutorials/expert-from-paste) - the agent-neutral paste flow (no MCP required)
* [Using Cubby with Codex](/tutorials/using-with-codex)
* [Using Cubby with Cursor](/tutorials/using-with-cursor)
* [CUBBY.md File](/platform/cubby-md) - Context file for AI assistants
* [`cubby deploy`](/cli-reference/deploy) - CLI deploy command
* [`cubby secrets`](/cli-reference/secrets) - CLI secrets management