> ## Documentation Index
> Fetch the complete documentation index at: https://bilt.me/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Desktop Setup

> Complete integration guide for Claude Desktop on macOS and Windows

## Overview

Connect Bilt MCP Server to Claude Desktop in under 5 minutes. Once configured, Claude can autonomously create, build, and deploy native mobile applications.

<Info>
  Claude Desktop supports MCP natively. No extensions or plugins required.
</Info>

## Platform Support

<CardGroup cols={2}>
  <Card icon="apple">
    **macOS**

    Full support for macOS 11+
  </Card>

  <Card icon="windows">
    **Windows**

    Full support for Windows 10+
  </Card>
</CardGroup>

<Warning>
  **Linux**: Claude Desktop is not officially available on Linux
</Warning>

## Prerequisites

1. **Claude Desktop installed** - Download from [claude.ai/download](https://claude.ai/download)
2. **Bilt API token** - Get one at [bilt.me/sign-up](https://bilt.me/sign-up)

***

## macOS Setup

### Step 1: Locate Config File

The config file is located at:

```
~/Library/Application Support/Claude/claude_desktop_config.json
```

### Step 2: Edit Configuration

Open Terminal and run:

```bash theme={null}
# Create the directory if it doesn't exist
mkdir -p ~/Library/Application\ Support/Claude/

# Edit the config file
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

### Step 3: Add Bilt Configuration

Paste this JSON:

```json theme={null}
{
  "mcpServers": {
    "bilt": {
      "transport": {
        "type": "sse",
        "url": "https://mcp.bilt.me/mcp/sse",
        "headers": {
          "Authorization": "Bearer bilt_live_YOUR_TOKEN_HERE"
        }
      }
    }
  }
}
```

Replace `YOUR_TOKEN_HERE` with your actual Bilt API token.

### Step 4: Save and Restart

1. Press `Ctrl+X`, then `Y`, then `Enter` to save
2. Quit Claude Desktop completely (`Cmd+Q`)
3. Reopen Claude Desktop

### Step 5: Verify Connection

In Claude, ask:

```
What MCP servers are connected?
```

You should see:

```
Connected MCP servers:
- bilt (7 tools available)
```

***

## Windows Setup

### Step 1: Locate Config File

The config file is located at:

```
%APPDATA%\Claude\claude_desktop_config.json
```

### Step 2: Create/Edit Configuration

1. Press `Win+R` to open Run dialog
2. Type: `notepad %APPDATA%\Claude\claude_desktop_config.json`
3. Click OK

If the file doesn't exist, Notepad will ask to create it - click Yes.

### Step 3: Add Bilt Configuration

Paste this JSON:

```json theme={null}
{
  "mcpServers": {
    "bilt": {
      "transport": {
        "type": "sse",
        "url": "https://mcp.bilt.me/mcp/sse",
        "headers": {
          "Authorization": "Bearer bilt_live_YOUR_TOKEN_HERE"
        }
      }
    }
  }
}
```

Replace `YOUR_TOKEN_HERE` with your actual Bilt API token.

### Step 4: Save and Restart

1. Click `File → Save`
2. Close Claude Desktop completely
3. Reopen Claude Desktop

### Step 5: Verify Connection

In Claude, ask:

```
What MCP servers are available?
```

You should see all 8 Bilt tools listed.

***

## Configuration Options

### Multiple Environments

Add separate entries for dev and production:

```json theme={null}
{
  "mcpServers": {
    "bilt-dev": {
      "transport": {
        "type": "sse",
        "url": "https://mcp.bilt.me/mcp/sse",
        "headers": {
          "Authorization": "Bearer bilt_live_DEV_TOKEN"
        }
      }
    },
    "bilt-prod": {
      "transport": {
        "type": "sse",
        "url": "https://mcp.bilt.me/mcp/sse",
        "headers": {
          "Authorization": "Bearer bilt_live_PROD_TOKEN"
        }
      }
    }
  }
}
```

Then specify which to use:

```
Use bilt-dev to create a test app
Use bilt-prod to deploy the final version
```

### Adding Other MCP Servers

You can connect multiple MCP servers:

```json theme={null}
{
  "mcpServers": {
    "bilt": {
      "transport": {
        "type": "sse",
        "url": "https://mcp.bilt.me/mcp/sse",
        "headers": {
          "Authorization": "Bearer bilt_live_YOUR_TOKEN"
        }
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
    }
  }
}
```

***

## Example Workflows

### Create Your First App

```
You: "Use Bilt to create a todo app"

Claude: [Uses bilt_create_project]
"I've created a new project called 'todo-app'. What features would you like?"

You: "Add login, todo list, and dark mode"

Claude: [Uses bilt_send_message]
"Building your app with those features. This will take about 2 minutes..."

[Wait for completion]

Claude: "Your app is ready! Would you like me to deploy it?"

You: "Yes, deploy it"

Claude: [Uses bilt_send_message with "deploy"]
"Deployed successfully! Your app is live at: https://todo-app-abc123.bilt.app"
```

### Add Features to Existing App

```
You: "Add a search feature to my todo app"

Claude: [Uses bilt_list_projects, finds todo-app]
[Uses bilt_send_message to add search]
"I've added a search bar at the top of your todo list. Testing the deployment now..."
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tools not appearing">
    **Symptom**: Claude doesn't show Bilt tools

    **Solutions**:

    1. Verify config file location is correct
    2. Check JSON syntax with [jsonlint.com](https://jsonlint.com)
    3. Ensure no extra commas or brackets
    4. Restart Claude completely (not just minimize)
    5. Check Claude's MCP logs:
       * macOS: `~/Library/Logs/Claude/mcp.log`
       * Windows: `%APPDATA%\Claude\Logs\mcp.log`
  </Accordion>

  <Accordion title="401 Unauthorized">
    **Symptom**: "Invalid or expired API key"

    **Solutions**:

    1. Verify token format starts with `bilt_live_`
    2. Check for extra spaces before/after token
    3. Regenerate token at bilt.me/settings/api-keys
    4. Ensure token hasn't expired
    5. Test token manually:
       ```bash theme={null}
       curl -H "Authorization: Bearer YOUR_TOKEN" \
         https://mcp.bilt.me/health
       ```
  </Accordion>

  <Accordion title="Connection timeout">
    **Symptom**: "Cannot connect to MCP server"

    **Solutions**:

    1. Check internet connection
    2. Verify firewall allows HTTPS (port 443)
    3. Try from different network
    4. Check Bilt status at [status.bilt.me](https://status.bilt.me)
    5. Disable VPN temporarily
  </Accordion>

  <Accordion title="Claude crashes on startup">
    **Symptom**: Claude won't open after adding config

    **Solutions**:

    1. Check JSON syntax - common errors:
       * Missing comma between entries
       * Extra comma after last entry
       * Unclosed brackets/braces
    2. Temporarily remove Bilt config
    3. Restart Claude to verify it works
    4. Re-add Bilt config carefully
  </Accordion>

  <Accordion title="Slow responses">
    **Symptom**: Claude takes long time to respond

    **Solutions**:

    1. This is normal for first request (cold start)
    2. Subsequent requests are faster
    3. Check your internet speed
    4. Try during off-peak hours
  </Accordion>
</AccordionGroup>

***

## Advanced Configuration

### Environment Variables (macOS only)

You can use environment variables for tokens:

1. Add to `~/.zshrc` or `~/.bash_profile`:
   ```bash theme={null}
   export BILT_API_TOKEN="bilt_live_YOUR_TOKEN"
   ```

2. Launch Claude from terminal:
   ```bash theme={null}
   source ~/.zshrc
   open -a "Claude"
   ```

<Warning>
  This method requires launching Claude from terminal each time
</Warning>

### Debug Mode

Enable verbose logging:

```json theme={null}
{
  "mcpServers": {
    "bilt": {
      "transport": {
        "type": "sse",
        "url": "https://mcp.bilt.me/mcp/sse",
        "headers": {
          "Authorization": "Bearer bilt_live_YOUR_TOKEN"
        }
      },
      "debug": true
    }
  }
}
```

Check logs:

* **macOS**: `tail -f ~/Library/Logs/Claude/mcp.log`
* **Windows**: Open `%APPDATA%\Claude\Logs\mcp.log`

***

## Security Best Practices

<CardGroup cols={2}>
  <Card icon="lock">
    **Never commit tokens**

    Don't add config file to git repositories
  </Card>

  <Card icon="key">
    **Rotate regularly**

    Generate new tokens every 90 days
  </Card>

  <Card icon="shield">
    **Use dev tokens**

    Separate tokens for development and production
  </Card>

  <Card icon="eye">
    **Monitor usage**

    Check API usage in Bilt dashboard
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/docs/api-reference/overview">
    Learn about all 7 tools
  </Card>
</CardGroup>