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

# Cursor Setup

> Complete integration guide for Cursor IDE on macOS, Windows, and Linux

## Overview

Connect Bilt MCP Server to Cursor IDE to enable AI-powered native mobile application development with seamless code generation, building, and deployment capabilities.

<Info>
  Cursor natively supports MCP through project-level or global configuration files.
</Info>

## Platform Support

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

    Full support for macOS 11+
  </Card>

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

    Full support for Windows 10+
  </Card>

  <Card icon="linux">
    **Linux**

    Full support for all major distros
  </Card>
</CardGroup>

## Prerequisites

1. **Cursor installed** - Download from [cursor.sh](https://cursor.sh)
2. **Bilt API token** - Get one at [bilt.me/sign-up](https://bilt.me/sign-up)

***

## Setup Options

You can configure Bilt MCP in two ways:

1. **Project-specific** (Recommended) - Only available in specific projects
2. **Global** - Available in all projects

### Project-Specific Setup (Recommended)

#### Step 1: Create Config Directory

In your project root:

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    mkdir -p .cursor
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    mkdir .cursor
    ```
  </Tab>
</Tabs>

#### Step 2: Create Config File

Create `.cursor/mcp_config.json`:

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    nano .cursor/mcp_config.json
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    notepad .cursor\mcp_config.json
    ```
  </Tab>
</Tabs>

#### Step 3: Add Bilt Configuration

```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: Reload Cursor

Press `Cmd/Ctrl + Shift + P` → Type "Reload Window" → Enter

***

### Global Setup

#### Step 1: Locate Global Config

<Tabs>
  <Tab title="macOS/Linux">
    ```
    ~/.cursor/mcp_config.json
    ```
  </Tab>

  <Tab title="Windows">
    ```
    %USERPROFILE%\.cursor\mcp_config.json
    ```
  </Tab>
</Tabs>

#### Step 2: Edit Config

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    mkdir -p ~/.cursor
    nano ~/.cursor/mcp_config.json
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    mkdir -Force "$env:USERPROFILE\.cursor"
    notepad "$env:USERPROFILE\.cursor\mcp_config.json"
    ```
  </Tab>
</Tabs>

#### Step 3: Add Configuration

Same JSON as project-specific setup:

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

#### Step 4: Restart Cursor

Quit Cursor completely and reopen.

***

## Verification

### Check Tool Availability

In Cursor's AI chat, ask:

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

You should see:

```
Available MCP servers:
- bilt (7 tools)
```

### Test a Tool

Try creating a project:

```
Use Bilt to create a test project called "hello-world"
```

Cursor should invoke `bilt_create_project` automatically.

***

## Configuration Options

### Environment Variables (Recommended)

Store tokens securely using environment variables:

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

Then set the variable:

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    # Add to ~/.zshrc or ~/.bashrc
    export BILT_API_TOKEN="bilt_live_YOUR_TOKEN"

    # Reload
    source ~/.zshrc

    # Launch Cursor from terminal
    cursor .
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    # Set permanently
    setx BILT_API_TOKEN "bilt_live_YOUR_TOKEN"

    # Restart Cursor
    ```
  </Tab>
</Tabs>

### Multiple Environments

Configure dev and production tokens:

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

Then specify which to use:

```
Use bilt-dev to create a test app
Use bilt-prod to deploy to production
```

### Team Configuration

Commit `.cursor/mcp_config.json` for team-wide access:

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

Add to `.gitignore`:

```
.cursor/mcp_config.local.json
```

Team members set their tokens:

```bash theme={null}
export BILT_API_TOKEN="their_token"
```

***

## Using Bilt in Cursor

### Natural Language Integration

Cursor automatically integrates Bilt tools into its AI workflow:

```
You: "Create a React dashboard app using Bilt"

Cursor: [Recognizes Bilt tools]
[Runs: bilt_create_project]
✓ Created project 'react-dashboard'

[Runs: bilt_send_message]
✓ Building React dashboard with charts and tables

"Project created! Building now..."
```

### Code Generation + Deployment

```
You: "Build this component and deploy it"

Cursor: [Generates code]
[Uses bilt_send_message to deploy]
✓ Deployed: https://react-dashboard-abc.bilt.app

"Your component is live!"
```

### Iterative Development

```
You: "Add a dark mode toggle"

Cursor: [Uses bilt_send_message]
✓ Added dark mode toggle to navigation

You: "Deploy the changes"

Cursor: [Uses bilt_send_message with "deploy"]
✓ Deployed successfully
```

***

## Cursor-Specific Features

### AI Chat Integration

Bilt tools appear in Cursor's AI chat automatically:

```
@bilt create a todo app
@bilt add authentication
@bilt deploy to production
```

### Inline Suggestions

When writing code, Cursor can suggest Bilt deployments:

```typescript theme={null}
// Your code here
function TodoApp() {
  // ...
}

// Cursor suggestion: "Deploy this app with @bilt?"
```

### Terminal Integration

Use Bilt commands in Cursor's integrated terminal:

```bash theme={null}
# Cursor can execute these via AI
cursor-ai "Use Bilt to list my projects"
cursor-ai "Deploy my-app to production"
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tools not appearing">
    **Check config location**:

    Project-specific: `project-root/.cursor/mcp_config.json`

    Global: `~/.cursor/mcp_config.json` or `%USERPROFILE%\.cursor\mcp_config.json`

    **Verify JSON syntax**:

    ```bash theme={null}
    # Use a JSON validator
    cat .cursor/mcp_config.json | python -m json.tool
    ```

    **Reload window**:
    `Cmd/Ctrl + Shift + P` → "Reload Window"
  </Accordion>

  <Accordion title="401 Unauthorized">
    **Check token format**:

    * Must start with `bilt_live_`
    * No extra spaces
    * No quotes inside the Bearer string

    **Test token**:

    ```bash theme={null}
    curl -H "Authorization: Bearer YOUR_TOKEN" \
      https://mcp.bilt.me/health
    ```

    Should return: `{"status":"ok"}`

    **Regenerate token**:
    Go to [bilt.me/settings/api-keys](https://bilt.me/settings/api-keys)
  </Accordion>

  <Accordion title="Connection timeout">
    **Check internet**:

    ```bash theme={null}
    ping mcp.bilt.me
    ```

    **Check firewall**:
    Ensure HTTPS (port 443) is allowed

    **Try different network**:
    Test on mobile hotspot or different WiFi
  </Accordion>

  <Accordion title="Cursor not loading config">
    **Check file permissions**:

    ```bash theme={null}
    ls -la .cursor/mcp_config.json
    ```

    Should be readable by your user.

    **Move to global config**:
    If project-specific isn't working, try global:

    ```bash theme={null}
    cp .cursor/mcp_config.json ~/.cursor/mcp_config.json
    ```
  </Accordion>
</AccordionGroup>

***

## Best Practices

<CardGroup cols={2}>
  <Card icon="folder">
    **Use project-specific**

    Keep configs isolated per project
  </Card>

  <Card icon="key">
    **Environment variables**

    Never commit tokens to git
  </Card>

  <Card icon="users">
    **Team sharing**

    Share config structure, not tokens
  </Card>

  <Card icon="rotate">
    **Rotate tokens**

    Update tokens every 90 days
  </Card>
</CardGroup>

### .gitignore Template

Add to your `.gitignore`:

```
# Cursor MCP configs with sensitive tokens
.cursor/mcp_config.local.json

# Keep team config template
!.cursor/mcp_config.json
```

Then in `.cursor/mcp_config.json`:

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

Team members set their own tokens via env vars.

***

## Keyboard Shortcuts

<CardGroup cols={2}>
  <Card>
    **Reload Window**

    `Cmd/Ctrl + Shift + P` → "Reload Window"
  </Card>

  <Card>
    **Open AI Chat**

    `Cmd/Ctrl + L`
  </Card>

  <Card>
    **Settings**

    `Cmd/Ctrl + ,`
  </Card>

  <Card>
    **Command Palette**

    `Cmd/Ctrl + Shift + P`
  </Card>
</CardGroup>

***

## Advanced Usage

### Custom Workspace Settings

Add to `.vscode/settings.json`:

```json theme={null}
{
  "cursor.mcp.autoStart": true,
  "cursor.mcp.debug": false,
  "cursor.ai.suggestions.enabled": true
}
```

### Multi-Project Setup

Different Bilt projects per workspace:

```json theme={null}
{
  "mcpServers": {
    "bilt-frontend": {
      "transport": {
        "type": "sse",
        "url": "https://mcp.bilt.me/mcp/sse",
        "headers": {
          "Authorization": "Bearer ${BILT_FRONTEND_TOKEN}"
        }
      }
    },
    "bilt-backend": {
      "transport": {
        "type": "sse",
        "url": "https://mcp.bilt.me/mcp/sse",
        "headers": {
          "Authorization": "Bearer ${BILT_BACKEND_TOKEN}"
        }
      }
    }
  }
}
```

***

## Next Steps

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

  <Card title="Cursor Docs" icon="book-open" href="https://cursor.sh/docs">
    Learn more about Cursor
  </Card>
</CardGroup>