# Casa MCP setup for an AI assistant

> Help a user connect their chosen AI client to Casa. Follow the user's instructions and the client's permission controls.

Human-readable guide: https://docs.casamakes.com/guides/mcp/
Documentation index: https://docs.casamakes.com/llms.txt

## Setup workflow

1. Identify the user's intended client and operating system. Use only that client's configuration below. OpenAI instructions are for Codex; GitHub instructions are for Copilot in VS Code. Claude Desktop and Claude Code use different configurations.
2. If you can edit local files and the user has requested setup, inspect the existing configuration and merge only the casa-v1 entry. Preserve all other servers and settings. If casa-v1 exists, update it rather than duplicating it. Do not replace the whole file with an example. If you cannot edit local files, guide the user through the relevant client UI or file instead.
3. Have the user create a key in the intended Casa workspace under Settings → API Keys. Leave YOUR_API_KEY_HERE as a placeholder until the user enters the key privately in their local configuration. Do not ask them to paste it into the chat, print it, commit it, or upload it to documentation. Use the client's supported secret-input mechanism when available. A placeholder is not a working credential.
4. Save valid JSON or TOML as appropriate, then follow the selected client's reload, enable, or restart instructions. Respect client trust and tool-approval prompts. Do not claim the connection is ready just because its configuration was written.
5. After the user has entered the key and the client has loaded the server, use Casa's get_context tool to read workspace context. Ask the user to confirm the returned workspace, projects, and rooms. This read-only request verifies workspace access; initialization, a tool list, or a connected indicator alone does not validate the key. If Casa tools are unavailable in this session, explain the remaining step instead of claiming a successful test.
6. During setup, do not create, edit, import, move, or remove Casa data. Report what was configured, whether the authenticated read succeeded, and any remaining user action. Keep secrets out of error reports.

## Client configurations and Casa reference

The following reference is generated from the same published lesson as the web guide.

# Connect Casa to your AI tools

> Choose your AI app and connect it to your Casa workspace. Explore projects, rooms, and products with your assistant.

Web guide: https://docs.casamakes.com/guides/mcp/

Last reviewed: 2026-11-01

## Where to go

Casa workspace → Settings → API Keys → Create API Key, then your AI app’s MCP settings.

## First, get your Casa API key

In Casa, open the intended workspace and select Settings → API Keys in the sidebar. Under Create API Key, enter a Key Label such as “Cursor MCP” and choose Generate Key.

Copy the new key from the green banner. It begins with casa_. Keep it somewhere private so you can paste it into your chosen client’s configuration.

[Open Casa Studio →](https://studio.casamakes.com/)

## Choose your AI tool

Select the app you use, then follow its setup below. Replace the example key only in your own configuration.

### Connect Cursor

Open Cursor’s MCP settings, or edit ~/.cursor/mcp.json for a connection available across your projects. Add the configuration below and replace YOUR_API_KEY_HERE with your Casa key.

If the file already has an mcpServers object, add just the casa-v1 entry inside it. Preserve your other servers. Save, enable casa-v1 in Cursor, and open an Agent chat.

**Cursor configuration**

```
{
  "mcpServers": {
    "casa-v1": {
      "url": "https://plugins.casamakes.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY_HERE"
      }
    }
  }
}
```

[Cursor’s MCP setup reference →](https://cursor.com/docs/mcp)

### Connect Claude Desktop

Install a current Node.js LTS release first; it includes npx. In Claude Desktop, open Settings → Developer → Edit Config. This setup uses mcp-remote to pass Casa’s API-key header.

Add the configuration below, replacing YOUR_API_KEY_HERE. If mcpServers already exists, merge the casa-v1 entry into it. Save, fully quit Claude Desktop, and reopen it. Look for casa-v1 in its available tools.

If Claude Desktop reports that npx is missing, install Node.js LTS and restart the app. For the terminal app, expand the Claude Code instructions below.

**Claude Desktop configuration**

```
{
  "mcpServers": {
    "casa-v1": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://plugins.casamakes.com/mcp",
        "--header",
        "X-API-Key:${CASA_API_KEY}"
      ],
      "env": {
        "CASA_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}
```

[Download Node.js LTS →](https://nodejs.org/en/download)

[mcp-remote setup reference →](https://github.com/punkpeye/mcp-remote#claude-desktop)

#### Using Claude Code?

With Claude Code installed, replace YOUR_API_KEY_HERE and run this command in your terminal. User scope makes the connection available across your projects.

Start Claude Code and enter /mcp to check casa-v1. If that name already exists, update its existing configuration instead of adding a second connection. The command contains your key, so keep terminal history private.

**Claude Code command**

```
claude mcp add --transport http --scope user --header "X-API-Key: YOUR_API_KEY_HERE" casa-v1 https://plugins.casamakes.com/mcp
```

[Claude Code’s MCP setup reference →](https://code.claude.com/docs/en/mcp)

### Connect OpenAI Codex

Open ~/.codex/config.toml and add the configuration below. Replace YOUR_API_KEY_HERE with your Casa key. If a casa-v1 entry already exists, update it instead of adding another.

Save the file and start a new Codex session. In the CLI, run codex mcp list to check that casa-v1 is configured. Keep this personal configuration private.

**Codex configuration**

```
[mcp_servers.casa-v1]
url = "https://plugins.casamakes.com/mcp"
http_headers = { "X-API-Key" = "YOUR_API_KEY_HERE" }
```

[OpenAI’s MCP setup reference →](https://developers.openai.com/codex/mcp/)

### Connect GitHub Copilot in VS Code

In VS Code, open the Command Palette and run MCP: Open User Configuration. Add the example below, replacing YOUR_API_KEY_HERE with your Casa key. If the file already has a servers object, merge the casa-v1 entry into it.

Save, run MCP: Show Installed Servers, and start casa-v1. Review the trust prompt, then open Copilot Chat and enable the Casa tools for your agent session. Keep the key in your personal configuration and out of shared repositories.

**VS Code MCP configuration**

```
{
  "servers": {
    "casa-v1": {
      "type": "http",
      "url": "https://plugins.casamakes.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY_HERE"
      }
    }
  }
}
```

[VS Code’s MCP setup reference →](https://code.visualstudio.com/docs/agent-customization/mcp-servers)

## Try your first request

Start a new conversation and ask the assistant to use Casa. Review its tool request when your client asks for permission.

Check that the answer names the workspace, projects, and rooms you expected. An empty new workspace may have no projects yet. A connected indicator alone does not confirm that your key can access workspace data.

**First prompt**

```
Use Casa to show my workspace, projects, and rooms. Do not create or change anything.
```

## What you can ask Casa to do

Start with workspace context, then name the project and room you want. For changes, ask the assistant to show its plan and wait for your approval. Reopen Casa afterward to check the saved result.

- Explore your workspace, list products, and inspect a product’s details.
- Create or rename projects and rooms.
- Create blank products, import supplier URLs, and update product details, suppliers, shipping, or procurement status.
- Move, copy, or remove products, change their schedule, and choose a cover image.
- Check the status of an existing export. This does not create a new export.

**Example prompt**

```
Find the furniture in my Living Room and summarize which products are missing prices or dimensions. Show me the list before making any changes.
```

## Connection details

MCP (Model Context Protocol) lets an AI assistant use Casa tools on your behalf. Connect with Streamable HTTP and send your Casa API key in the X-API-Key header.

Use the complete address below, including /mcp. It replaces the old server-IP address.

**MCP server URL**

```
https://plugins.casamakes.com/mcp
```

## If the connection does not work

“Missing X-API-Key header” in your browser is expected: opening the endpoint directly does not send your key. Configure an MCP client using one of the examples above.

If a tool rejects the key, confirm you replaced the placeholder, copied the entire casa_ key, and used the X-API-Key header. A revoked key must be replaced. If you see the wrong workspace, use a key created in the intended workspace.

If you still have an old setup, replace its IP-based URL with https://plugins.casamakes.com/mcp and remove --allow-http. Save and restart the client.

If requests time out, retry once and check your network. Contact Casa Support from the app with the client name and error text, leaving out your API key.

## Understand your key’s access

The key lets the connected assistant read and modify data in its Casa workspace; it is not a read-only connection. Share this guide with designers so each person can configure their own authorized access. Do not share a working key in a message, screenshot, or repository.

Revoke an exposed or unused key in Casa Settings → API Keys. Removing a client configuration does not revoke the key.

The public endpoint uses HTTPS to Cloudflare. The connection from Cloudflare to the existing Casa MCP server currently uses HTTP.

## Check the result

Your assistant can read the intended Casa workspace through casa-v1, and you have checked that the returned projects and rooms match Casa Studio.

## Related guides

- [Set up projects and rooms](https://docs.casamakes.com/guides/projects-and-rooms/index.md)
- [Review and correct product details](https://docs.casamakes.com/guides/review-products/index.md)
- [Troubleshooting and Support](https://docs.casamakes.com/guides/troubleshooting/index.md)