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 Desktop, 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. 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.

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.

Claude Desktop¶

The Claude Desktop app configures MCP servers through a JSON file. Its built-in connector UI is designed around OAuth and doesn't offer a custom-header field, so Indigo's key-based endpoint is connected through a small bridge called mcp-remote, which forwards Claude Desktop's local connection to Indigo's HTTP endpoint and adds your Authorization header.

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.

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.

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. The same goes for the Connectors screens in claude.ai and in Claude Desktop; in Claude Desktop, use the setup above instead. 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 Desktop or Claude Code.

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

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

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 Claude Desktop, 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.

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.