Connecting a chat client to Indigo¶

New in 2026.1 The Indigo Web Server includes an MCP server — a standard way for AI chat assistants to talk to your Indigo home. Once a client is connected, you can ask it about your devices and have it control them, run your action groups, and read or set variables, all in plain language. This page covers connecting three kinds of clients: Claude's chat apps (on the web, the Mac, and iPhone or Android), the Claude Code command line, and other MCP-capable clients. ChatGPT can't connect yet; see below. For what you can actually do once connected, see Using Indigo from a Chat Client.

What "MCP" is, in one sentence

MCP (Model Context Protocol) is an open standard that lets an AI assistant call tools on an external system. Indigo exposes a set of home-automation tools — list devices, turn things on, run an action group, and so on — and any MCP client can connect to them.

Before you start¶

You need three things in place on the Indigo side.

Indigo 2026.1 or later, with the Indigo Web Server enabled. It is part of the Indigo Server and is normally running already.
API key authentication turned on. In Indigo, open the Start Local Server dialog (the same place you set the web server's port) and make sure "Enable OAuth and API Key authentication" is checked. If this is off, no key will work.
A key to authenticate with. You have two choices — pick whichever suits you:
- An Indigo API key. Create and manage these in the Authorizations section of your Indigo Account. API keys are validated through your Indigo account, and you can revoke any key instantly without affecting your other keys or your username/password.
- A local secret. This is a key that validates entirely on your own machine, with no internet round-trip — handy for a purely local setup. Create a file named secrets.json in your Indigo install folder's Preferences directory, for example:
```
/Library/Application Support/Perceptive Automation/Indigo 2026.1/Preferences/secrets.json
```
The file is a JSON list of strings; each string is a usable key:
```
[
    "my-first-mcp-key",
    "another-key-if-you-want-one"
]
```
Restart the Indigo Server after editing secrets.json — it is read only at startup. A local secret is then used exactly like an API key in the steps below.

It's best practice (and highly recommended) that you create a separate key for your MCP client(s). See the WebSockets API page for more on authentication options.

Keep your key handy — you will paste it into each client's configuration.

A note on keys

A key lets a client control your published devices and run your automations, but it cannot modify your database (it can't add or delete devices, triggers, schedules, or action groups). Treat the key like a password: don't post it in the user forums or share it with anyone you don't trust.

Where the MCP server lives (the URL)¶

The MCP server is reached at this path on your Indigo Web Server:

/v3/api/mcp

How you build the full URL depends on how your web werver is configured — specifically whether it's running with HTTPS (secure connections) turned on, which you set in the Start Local Server dialog. There are three ways to connect; pick the one that matches your setup. 8176 below is the default Web Server port — substitute yours if you changed it (it's shown in Start Local Server).

Option A — Indigo Reflector (easiest if you have a subscription)¶

If your server uses the Indigo Reflector, connect through your reflector address:

https://YOUR-REFLECTOR.indigodomo.net/v3/api/mcp

The reflector has a proper, authority-signed certificate, so there's nothing extra to configure — no cert wrangling, no port, and it works whether the client is on your network or elsewhere. This is the simplest path for most clients, and the only one a claude.ai connector can use. Your reflector name is shown in the Start Local Server dialog (reflector settings) and in your Indigo Account; the reflector requires an active Indigo subscription.

Option B — Local HTTPS with Indigo's self-signed certificate¶

If you run the Web Server locally with secure connections (HTTPS) enabled — a very common setup — and the client is on the same Mac as Indigo, the URL is:

https://localhost:8176/v3/api/mcp

The catch: Indigo's local certificate is self-signed (there's no way to get an authority-signed cert for a name like localhost). Most clients reject a self-signed cert by default, so the connection fails until you tell the client to trust Indigo's certificate. The certificate file lives at:

/Library/Application Support/Perceptive Automation/Indigo 2026.1/Web Assets/cert/indigo-cert.pem

(More generally, <your Indigo install folder>/Web Assets/cert/indigo-cert.pem.) The client-specific sections below show how to point each client at this file. Note that with secure connections enabled, the server speaks only HTTPS on port 8176 — a plain http:// URL on that port will not work.

This certificate is issued only for the name localhost, so Option B works when the client runs on the same Mac as Indigo. To reach a secure server from another device, use the reflector (Option A) — connecting to the Mac's LAN IP over HTTPS will fail certificate validation even with the cert trusted, because the IP isn't on the certificate.

Not recommended for ongoing use

The certificate path includes the Indigo version (.../Indigo 2026.1/Web Assets/...). When you upgrade Indigo to a new version, that folder name changes, so NODE_EXTRA_CA_CERTS will point at a path that no longer exists and the connection will break until you edit every client config to the new version's path. If you have a reflector, Option A avoids this entirely and is the better long-term choice; use Option B mainly for same-Mac testing or when you have no reflector.

Option C — Plain local HTTP (only if HTTPS is off)¶

If your Web Server is not using secure connections, it serves plain HTTP and there's no certificate to deal with:

http://localhost:8176/v3/api/mcp           (same Mac)
http://YOUR-INDIGO-MAC-IP:8176/v3/api/mcp  (another device on your network)

This is the simplest local option, but the key (and traffic) travel unencrypted, so use it only on a network you trust. On localhost the traffic never leaves your Mac. To find your Mac's network address, check System Settings → Network, e.g. http://10.0.1.20:8176/v3/api/mcp.

In every client below, the authentication is the same regardless of which option you chose: an HTTP header

Authorization: Bearer YOUR-KEY

where YOUR-KEY is your API key or local secret.

Choosing a setup for Claude¶

There are two ways to connect Claude's chat apps (on the web, the Mac, and iPhone or Android) to Indigo. Claude Code has its own setup, below; this choice doesn't apply to it.

Easy: a claude.ai connector. You add Indigo once, in your Claude account. Anthropic's servers then connect to Indigo through your reflector, and Indigo works in every Claude app you sign in to, including voice mode.
Local: Claude Desktop with mcp-remote. A small bridge on your Mac connects Claude Desktop to Indigo. It takes more setup and works only in Claude Desktop on that Mac, but your key stays on your Mac and the connection can stay entirely on your own network.

	Easy: claude.ai connector	Local: Claude Desktop with `mcp-remote`
Works in	Claude on the web, Claude Desktop, and Claude for iOS and Android, from one setup	Claude Desktop, on the Mac where you set it up
Voice mode	Yes	No
You need	An Indigo Reflector subscription, and the Request headers option in your Claude account (see the note below)	Node.js, and some editing of a JSON configuration file
Connects via	Anthropic's servers, then your reflector	Your Mac, directly to Indigo or through your reflector
Your key	Stored by Anthropic with the connector, so you are trusting a third party with it, and anyone signed in to your Claude account can use the connector	Stays on your Mac. With a local secret and a direct connection, nothing leaves your network

Voice mode and dictation are different

Dictation (the microphone icon) turns your speech into text in the message box, and works with either setup. Voice mode (the sound-wave icon) is a spoken conversation, and it can only use connectors that belong to your Claude account, so it needs the Easy setup. With the Local setup, Indigo's tools are missing from voice mode.

Easy: a claude.ai connector¶

You add Indigo as a custom connector in your Claude account, and it then appears in every Claude app you sign in to. You need two things first:

The Indigo Reflector. The connection to Indigo is made by Anthropic's servers, not by your Mac, and they can only reach Indigo at a public address. A localhost or local network address won't work here; use Option A.
The Request headers option. Indigo authenticates with your key in a request header. Claude supports that through Request headers, a beta that Anthropic is still rolling out. If the Add custom connector dialog has no Request headers section, your account doesn't have it yet, and you'll need the Local setup for now.

To add the connector:

Go to claude.ai, open Customize → Connectors, and click Add custom connector. The same dialog is in the Claude app on your iPhone or Android device. On a Team or Enterprise plan, an Owner adds it for the organization from Organization settings → Connectors instead.
Name it Indigo, enter your reflector URL as the server URL, and continue:
```
https://YOUR-REFLECTOR.indigodomo.net/v3/api/mcp
```
Check the domain: it's indigodomo.net. Claude may first try to sign in with OAuth, which Indigo doesn't support yet. When that fails, it shows the authentication settings below. The failed sign-in is expected, not an error.
For Authentication, choose No sign-in. Don't leave it on Sign in now: Claude can't send your key in the authorization header on an OAuth connection.
Under Request headers, click Add header, choose the header name authorization, and enter this as the value:
```
Bearer YOUR-KEY
```
Include the word Bearer and the space after it. Claude sends the value exactly as you type it, and a bare key gets a 401 from Indigo, which claude.ai reports as "couldn't reach the server."
Click Add. If Claude Desktop or the mobile app is already open, quit and reopen it to pick up the new connector.

Then start a chat and ask about your house. You can turn the connector on or off for a single chat with the + button, under Connectors.

You can't edit the header once it's saved. To change the key, for example after revoking it, remove the connector and add it again.

Your key is held by Anthropic

With this setup, your key is stored by Anthropic along with the connector, and anyone who can sign in to your Claude account can control your published devices from any device. Use a key you created only for this, so you can revoke it without affecting anything else, and protect your Claude account, and the email, Google or Apple account you sign in with, as you would your Indigo account. If you would rather your key never leave your Mac, use the Local setup.

Local: Claude Desktop with `mcp-remote`¶

This setup connects Claude Desktop to Indigo from your own Mac, through a small bridge called mcp-remote. The bridge forwards Claude Desktop's local connection to Indigo's HTTP endpoint and adds your Authorization header. It's set up in Claude Desktop's configuration file, not in its Connectors screen, which is the Easy setup.

Use it if you don't have a reflector subscription, if your Claude account doesn't have the Request headers option yet, or if you want your key to stay on your Mac. Indigo's tools are then available in Claude Desktop's chats on this Mac, including with dictation, but not in voice mode or on your phone. See Choosing a setup for Claude.

mcp-remote is a Node.js program that Claude Desktop starts with npx, so you need Node.js installed on the Mac that runs Claude Desktop. Most Macs don't have it. If you haven't installed it before, follow Installing Node.js first, including the checks at the end. Then run this in Terminal to confirm that mcp-remote itself downloads and runs:

npx -y mcp-remote --help

The first run takes a few seconds while npx downloads the package. It should then print a line beginning Usage: mcp-remote. If it does, Node is working and any later problem is in the configuration below.

Open Claude Desktop's config file (Settings → Developer → Edit Config), or edit it directly at:
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
Add an indigo entry under mcpServers, using the URL for your connection option. The reflector (Option A) is simplest — its certificate is already trusted:

{
  "mcpServers": {
    "indigo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR-REFLECTOR.indigodomo.net/v3/api/mcp",
        "--header",
        "Authorization:${INDIGO_AUTH}"
      ],
      "env": {
        "INDIGO_AUTH": "Bearer YOUR-KEY"
      }
    }
  }
}

For local HTTPS with the self-signed cert (Option B), use the https://localhost:8176 URL and add NODE_EXTRA_CA_CERTS to the env block so the bridge trusts Indigo's certificate:

{
  "mcpServers": {
    "indigo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://localhost:8176/v3/api/mcp",
        "--header",
        "Authorization:${INDIGO_AUTH}"
      ],
      "env": {
        "INDIGO_AUTH": "Bearer YOUR-KEY",
        "NODE_EXTRA_CA_CERTS": "/Library/Application Support/Perceptive Automation/Indigo 2026.1/Web Assets/cert/indigo-cert.pem"
      }
    }
  }
}

For plain local HTTP (Option C), use the http://localhost:8176 URL and drop the NODE_EXTRA_CA_CERTS line.

If which npx printed anything other than /usr/local/bin/npx (for example, you installed Node with Homebrew or nvm), Claude Desktop may not find it, because it doesn't see the path your Terminal uses. Use the full path as the command, and add a PATH entry to env that starts with the same folder, so that npx can find node in turn:

```json
"command": "/opt/homebrew/bin/npx",
...
"env": {
  "INDIGO_AUTH": "Bearer YOUR-KEY",
  "PATH": "/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
}
```

Substitute the folder which npx actually printed. See Apps that don't run from Terminal for why this is needed.

Save the file and quit and reopen Claude Desktop (Claude → Quit Claude, not just closing the window). Indigo's tools will appear in the client (look for the tools/connector indicator), and you can start asking about your home.

If they don't appear, Claude Desktop keeps a log for each MCP server it starts. Indigo's is ~/Library/Logs/Claude/mcp-server-indigo.log, and it shows the actual error: Node not found, a certificate problem, or a 401 from Indigo. See Troubleshooting below.

Why the header looks split up

The whole credential — Bearer YOUR-KEY — goes in the env block, and the header argument references it as Authorization:${INDIGO_AUTH} with no space after the colon. This avoids a known bug where Claude Desktop mangles spaces inside arguments. Putting the key in env also keeps it out of the argument list.

The configuration file holds your key in plain text, so keep it to yourself: don't post it in the forums when asking for help, and remove the key from any copy you share.

If Claude Desktop runs on a different Mac than Indigo, replace localhost with your Indigo Mac's network address (e.g. https://10.0.1.20:8176/v3/api/mcp). The self-signed certificate is issued for localhost, so connecting to it by IP address may still be rejected even with NODE_EXTRA_CA_CERTS set — the reflector (Option A) avoids this entirely and is the recommended choice for cross-device use.

Claude Code (command line)¶

Claude Code has first-class support for HTTP MCP servers with an auth header, so this is the quickest path. Use the URL from whichever connection option above matches your setup. For the reflector (Option A), there's nothing special to do:

claude mcp add --transport http indigo https://YOUR-REFLECTOR.indigodomo.net/v3/api/mcp \
  --header "Authorization: Bearer YOUR-KEY"

Notes:

All options (--transport, --header, …) must come before the server name (indigo).

To avoid putting the key directly in your shell history, set it in an environment variable and reference it — Claude Code expands ${VAR} at startup:

export INDIGO_KEY="your-key"
claude mcp add --transport http indigo https://YOUR-REFLECTOR.indigodomo.net/v3/api/mcp \
  --header "Authorization: Bearer ${INDIGO_KEY}"

Local HTTPS with the self-signed cert (Option B): Claude Code runs on Node, so make it trust Indigo's certificate by exporting NODE_EXTRA_CA_CERTS before launching Claude Code (and use the https://localhost:8176/... URL):

export NODE_EXTRA_CA_CERTS="/Library/Application Support/Perceptive Automation/Indigo 2026.1/Web Assets/cert/indigo-cert.pem"
claude mcp add --transport http indigo https://localhost:8176/v3/api/mcp \
  --header "Authorization: Bearer ${INDIGO_KEY}"

The variable must be set in the environment where the claude process actually runs, so add the export to your shell profile if you want it to persist.

Plain local HTTP (Option C): just use the http://localhost:8176/... URL — no cert handling needed.
Verify it connected with claude mcp list. You can then ask Claude things like "list my Indigo devices."

To remove it later: claude mcp remove indigo.

Other MCP clients¶

ChatGPT can't connect yet

ChatGPT's custom connectors offer only OAuth or no authentication, with no way to send an Indigo API key, and Indigo doesn't support OAuth yet. ChatGPT's connectors also run on OpenAI's servers, so the mcp-remote bridge described below can't help. Until Indigo supports OAuth, use a client that can send the Authorization header, such as Claude or Claude Code.

This applies to ChatGPT's chats, on the web, the desktop app and mobile. Codex, OpenAI's coding agent, is different: it can send the header, including in the ChatGPT desktop app's Codex mode. See Coding agents.

Any MCP client that speaks the standard streamable-HTTP transport can connect to Indigo. What differs between clients is how they let you authenticate. Indigo's endpoint expects a static bearer token, so the client must be able to send a custom Authorization header.

Give the client these connection details:

Server URL: the URL from your connection option above. The reflector (https://YOUR-REFLECTOR.indigodomo.net/v3/api/mcp) is the easiest, because its certificate is already trusted — most clients have no way to point at Indigo's local self-signed cert, so a local HTTPS URL will fail. A client that runs on your Mac can get around that by going through mcp-remote with NODE_EXTRA_CA_CERTS, as in the Claude Desktop section.
Transport: streamable HTTP
Auth header: Authorization: Bearer YOUR-KEY

Two situations come up:

The client lets you set a custom request header. Enter the URL and add the Authorization: Bearer YOUR-KEY header. You're done.
The client's connector only offers OAuth or "no authentication," with no field for a static bearer token. If the client runs on your Mac and can start a local MCP server from a command, use the same mcp-remote bridge shown in the Claude Desktop section above. mcp-remote gives the client a local MCP connection and adds your Authorization header on the way to Indigo. It needs Node.js.

mcp-remote can't help a client that runs in the cloud, such as ChatGPT's connectors or claude.ai's, which run on their makers' servers. There is nowhere to run the bridge, so such a client can connect to Indigo only if its own settings let it send the Authorization header, as claude.ai's Request headers option does.

The endpoint, key, and header are identical across all clients; only the place you type them in changes.

Coding agents and plugin development¶

If you write Indigo plugins, a coding agent with this connection can run the whole edit cycle without you leaving the editor: change the code, reload the plugin, read the event log to see what it printed, and check a device's state to confirm the change worked. restart_plugin was added for exactly this.

Setup is the easy case. Coding agents let you set a request header directly, so none of them need the mcp-remote bridge:

Agent	How to add it
Claude Code	`claude mcp add --transport http …`, as above
Cursor	MCP settings, HTTP server with a custom `Authorization` header
VS Code (GitHub Copilot)	MCP server configuration, HTTP transport with a custom header
Windsurf, Zed, Cline	as above — an HTTP server URL plus an `Authorization` header
Codex	`~/.codex/config.toml`, shown below

Codex reads its MCP servers from ~/.codex/config.toml. The Codex command line, the IDE extension, and Codex mode in the ChatGPT desktop app all share that file, and the desktop app's Settings → Plugins → MCPs screen edits it. Add Indigo like this:

[mcp_servers.indigo]
url = "https://YOUR-REFLECTOR.indigodomo.net/v3/api/mcp"
http_headers = { Authorization = "Bearer YOUR-KEY" }

To keep the key out of the file, use bearer_token_env_var = "INDIGO_KEY" instead of http_headers, and set INDIGO_KEY to the key alone, without Bearer. The ChatGPT desktop app doesn't see variables you export in Terminal, though, so the desktop app needs the http_headers form. Indigo is then available to Codex, not to ChatGPT's ordinary chats.

Two things to know before you wire it into a loop:

restart_plugin is confirmation-gated. It returns a confirmation token rather than acting, and the agent has to pass that token back through the confirm tool before the restart happens. The first response is not a failure; it's the gate. It also refuses to restart the Web Server plugin, since that would cut the connection it's talking over.
Restart is the only operation. You can't start a plugin that wasn't running or stop one that is, the same constraint the indigo-restart-plugin command line tool has.

The other ways to reload a plugin during development — the command line tool, the PyCharm external tool, and plugin.restartAndDebug() — are in Setting Up a Development Environment.

Troubleshooting¶

For the Local Claude Desktop setup, start with the log: ~/Library/Logs/Claude/mcp-server-indigo.log. It records the errors listed below, which Claude Desktop itself doesn't show.

This section covers connecting. For problems once you're connected, such as the assistant not finding a device or picking the wrong one, see Troubleshooting in Using Indigo from a Chat Client.

claude.ai says it "couldn't reach the server" when you add the connector. Usually the header value is missing the word Bearer and the space after it, so Indigo answered 401. Also check that the URL is your reflector address; Anthropic's servers can't reach a localhost or local network address. You can't edit a saved header, so remove the connector and add it again.
There's no Request headers section in claude.ai's Add custom connector dialog. Your account doesn't have that beta yet. Use the Local setup until it does.
Indigo works when you type, but not in voice mode or on your phone. You're using the Local setup, which only Claude Desktop's chats on that Mac can see. Voice mode and the mobile apps use connectors in your Claude account; see Easy: a claude.ai connector.
spawn npx ENOENT, or env: node: No such file or directory. Claude Desktop couldn't find Node. If node --version also fails in Terminal, Node isn't installed: see Installing Node.js. If it works in Terminal, Node is installed somewhere Claude Desktop doesn't look. Use the full path to npx and add a PATH entry, as shown in the Claude Desktop steps.
401 / authentication failed. The key is wrong, "Enable OAuth and API Key authentication" is unchecked in Start Local Server, or (for a local secret) you edited secrets.json but didn't restart the Indigo Server.
Connection refused / wrong scheme. Check the host and port (default 8176) and confirm the Indigo Web Server is running. Match the scheme to your server: if secure connections are on, you must use https:// (a plain http:// URL on port 8176 won't answer); if they're off, use http://.
TLS / certificate errors on a local HTTPS connection. Your client is rejecting Indigo's self-signed certificate. Either trust it via NODE_EXTRA_CA_CERTS (Option B above), or connect through the reflector (Option A), which has a trusted certificate.
Connected, but a device you expected isn't there, or the assistant can't find it. The MCP server only sees objects marked for remote display, and how well it understands indirect phrasing depends on your Mac. See Troubleshooting in Using Indigo from a Chat Client.
A control action says it needs confirmation. That's expected for locks, garage/door controllers, and anything you've flagged. See the confirmation section in Using Indigo from a Chat Client.