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

# Free Remote MCP for Home Assistant

## Intro

[Homeway's free remote MCP server for Home Assistant](https://homeway.io/mcp?source=help_mcp_getstarted) allows any AI assistant or agent to fully integrate with your Home Assistant. Your AI assistant will be able to access live status information about your home, control any device in your home, send commands, and more.

## Ease Of Use

Homeway's cloud AI MCP server is easy to set up. [Simply install our Home Assistant App](https://homeway.io/getstarted?source=help_mcp_install_app), log in to the MCP server, and you're done. It's private and secure by default and accessible to any AI.

## Security

Homeway's MCP granular control allows you to enable/disable access to any MCP function, ensuring the model has no access to it. This allows you to make your home read-only or allow the AI access to only a subset of controls. The granular control permissions are enforced by Homeway's servers, so there's no way for the AI to get around them.

## Privacy

The cloud MCP server is built on Homeway's worldwide secure and private server infrastructure. Homeway sticks to a strict [Privacy Commitment; you can read more about it here.](https://help.homeway.io/privacy)

## Get Started

[Click here to set up your Home Assistant](https://homeway.io/getstarted?source=help_mcp_get_started) or choose a client below for a full step-by-step guide.

## AI Setup Guides

### Claude

1. Open the Claude app and navigate to **Customize** > **Connectors**.
2. Click the "Add" or "+" button and select **Add Connector**.
3. Enter the MCP server URL: `https://homeway.io/api/mcp`.
4. Click Connect after saving, then follow the on-screen prompts to complete OAuth sign-in and authorization.

### ChatGPT

1. Open ChatGPT and go to **Settings** > **Apps** > **Advanced Settings**.
2. Turn on **Developer Mode**.
3. Click **Create App**.
4. Enter the MCP server URL: `https://homeway.io/api/mcp`
5. Save the configuration and follow the prompts to complete OAuth sign-in and authorization.

### Google Gemini

The Homeway MCP server will work everywhere in Gemini, but it must be set up in the desktop app or website.

1. Open the Gemini desktop app or website in your browser.
2. Click the settings gear icon and then select "Connected Apps"
3. Scroll to the bottom and select "Add a custom app"
4. Enter the MCP server URL: `https://octoeverywhere.com/api/mcp`
5. Click Next
6. Approve the permissions

<Tip>
  Sometimes the Gemini Custom App setup will fail, saying something about a linked account being required. Simply retry a few times, and the error will resolve itself.
</Tip>

### Claude Code

1. Run the following command in your terminal:

```text theme={null}
claude mcp add --transport http homeway https://homeway.io/api/mcp
```

2. In your Claude Code session, run `/mcp` and follow the prompts to complete the OAuth authorization flow.
3. To use a Bearer Token instead, add the `--header` flag:

```text theme={null}
claude mcp add --transport http homeway https://homeway.io/api/mcp --header "Authorization: Bearer YOUR_TOKEN_HERE"
```

### Cursor

1. Open Cursor and go to **Cursor Settings**.
2. In the left sidebar, select **Tools & MCP**, then click **Add Custom MCP**.
3. Edit the `.cursor/mcp.json` file and add the following content:

```text theme={null}
{
  "mcpServers": {
    "homeway": {
      "url": "https://homeway.io/api/mcp"
    }
  }
}
```

4. Save the configuration, then reopen **Tools & MCP**.
5. Find Homeway in the installed MCP services list, click **Connect**, and complete OAuth sign-in and authorization in your browser.
6. To use a Bearer Token, add the `headers` field to the configuration instead:

```text theme={null}
{
  "mcpServers": {
    "homeway": {
      "url": "https://homeway.io/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}
```

### VS Code

1. Create or edit the `.vscode/mcp.json` file in your workspace and add the following content:

```text theme={null}
{
 "servers": {
    "homeway": {
      "type": "http",
      "url": "https://homeway.io/api/mcp"
    }
  }
}
```

2. You can also open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P), run **Add Server**, choose **HTTP (HTTP or Server-Sent Events)**, enter the MCP server URL `https://homeway.io/api/mcp` and an ID, then choose whether to apply it to the workspace or globally.
3. Save the configuration and follow the prompts to complete OAuth sign-in and authorization in your browser.
4. To use a Bearer Token, add the `headers` field to the configuration instead:

```text theme={null}
{
  "servers": {
    "homeway": {
      "type": "http",
      "url": "https://homeway.io/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}
```

### Codex

**Via the Codex App**

1. Open the Codex App and go to **Settings > MCP Servers**.
2. Click **Add Server**.
3. Select **Streamable HTTP**.
4. Enter the MCP server URL: `https://homeway.io/api/mcp`
5. Click **Authenticate** after saving, then follow the on-screen prompts to complete OAuth sign-in and authorization.

**Via the CLI**

1. Run the following command in your terminal:

```text theme={null}
codex mcp add homeway --url https://homeway.io/api/mcp
```

2. You will be automatically prompted to complete OAuth sign-in and authorization in your browser.

### TRAE

1. Open TRAE and go to **Settings**.
2. In the left sidebar, select **MCP**, then click **Add > Add Manually**.
3. Add the following configuration:

```text theme={null}
{
  "mcpServers": {
    "homeway": {
      "url": "https://homeway.io/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.