Large Language Models

ChatGPT Home Assistant MCP: Not Working Fixes, Remote Access and Free Setup

ChatGPT refuses to connect to your Home Assistant MCP server, or connects but never controls anything? This article walks through the real causes: OAuth failures, missing remote access, blocked tool calls and wrong URLs. It also shows how to build a free remote access setup and keep the whole thing secure.

ChatGPT Home Assistant MCP: Not Working Fixes, Remote Access and Free Setup
Cristian Da Conceicao

You typed the MCP server URL into ChatGPT, pressed connect, and got a spinner that never ends. Or worse: a cryptic message about an OAuth client that could not be resolved. If your ChatGPT Home Assistant MCP link is not working, you are in good company. This is the single most common wall people hit when they try to talk to their smart home through a chatbot, and almost every case traces back to one of five causes: the server is unreachable from the internet, the OAuth discovery fails behind a proxy, the URL is wrong, the integration is not exposing the right entities, or the tool calls are being blocked on the ChatGPT side.

This article walks through each cause in the order you are most likely to meet it, then builds a free remote access setup so you do not have to pay for anything just to get a chat window to reach your living room.

💡 Quick answer: ChatGPT on the website runs in the cloud. Cloud services cannot see homeassistant.local. Your instance needs a public HTTPS address, and that address must pass OAuth discovery cleanly. Fix those two things and most "not working" cases disappear.

A frustrated user at a laptop with a red error message and handwritten notes on a desk

What MCP Actually Does Here

MCP stands for Model Context Protocol. Think of it as a standard plug between an AI assistant and a tool. Home Assistant ships an MCP server integration that exposes the entities and services you choose, so an AI client can read states ("is the garage door open?") and call actions ("turn off the kitchen light").

The flow looks simple on paper:

  1. You enable the MCP server integration in Home Assistant.
  2. You decide which entities the assistant may see, using the Assist exposure settings.
  3. You paste the server URL into ChatGPT as a custom connector and choose OAuth as the authentication method.
  4. ChatGPT discovers the OAuth endpoints, sends you through a login, and lists the tools.

Every one of those steps can fail quietly. The rest of this article is a map of where.

The endpoint you need

The built-in integration serves its endpoint at the /api/mcp path of your Home Assistant address. Older community tutorials still mention a /mcp_server/sse path, which comes from the earlier days of the feature. If you are following a tutorial that is more than a few months old, check which path it uses before blaming your network.

Local clients versus cloud clients

A desktop client that runs on your own computer can often reach your instance over the local network. ChatGPT on the web cannot. This difference explains a surprising number of forum threads where "it worked on my laptop but not in the browser."

Client typeWhere the request comes fromNeeds public access?
Desktop app on your home networkYour own computerUsually no
ChatGPT on the websiteOpenAI serversYes
Mobile app on mobile dataCloud or phone, outside your LANYes
Local script or agentSame networkNo

Why ChatGPT Cannot Connect

Let's go through the failures from most to least common.

Cause 1: No public address

If your Home Assistant URL ends in .local, starts with 192.168, or only works on your Wi-Fi, ChatGPT will never reach it. The Home Assistant documentation is blunt about this: when the AI agent runs in the cloud, the instance must be reachable from the internet, for example through Home Assistant Cloud or another remote access method.

How to test: turn off Wi-Fi on your phone, open your external URL in a mobile browser, and see whether the login page loads. If it does not, the problem is not ChatGPT at all.

A white home router with green status lights and a blue ethernet cable on a wooden shelf

Cause 2: OAuth discovery breaks behind a proxy

This one produces the famous error: "Failed to resolve OAuth client for MCP connector." Community reports show it appearing on instances behind a custom domain, a tunnel or a reverse proxy. The usual reason is that the metadata Home Assistant returns during discovery does not match the address ChatGPT used to reach it.

Common triggers:

  • The external URL in Home Assistant settings differs from the address you pasted into ChatGPT.
  • A reverse proxy rewrites the host header, so Home Assistant advertises an internal address.
  • trusted_proxies and use_x_forwarded_for are missing in the http: configuration, so the instance does not trust forwarded headers.
  • A redirect from http to https, or from a bare domain to www, changes the issuer halfway through the handshake.

💡 Fix order: set the external URL to the exact public HTTPS address you will paste into ChatGPT, add your proxy to the trusted proxies list, restart, then remove and re-add the connector. Do not just retry the old one. A cached failed registration can keep failing.

Cause 3: The connector is added but tools never run

Some users complete the OAuth login, see the tools listed, and then every call is refused. There are community threads about tool calls being blocked on the OpenAI side even when the connection itself looks healthy. If your tools show up but nothing happens:

  • Re-check that you are on a ChatGPT plan and mode that allows custom connectors with write actions. Plan requirements for custom MCP connectors have changed more than once, so check the current settings screen rather than an old article.
  • Start with a read-only request such as "what is the temperature in the hallway?" before asking for an action.
  • Open a fresh chat. Connectors enabled mid-conversation sometimes do not attach.

Cause 4: The wrong URL form

People paste one of these and wonder why nothing works:

What you pastedProblem
http://homeassistant.local:8123/api/mcpLocal only, and not HTTPS
https://myhome.example.comMissing the MCP path
https://myhome.example.com/api/mcp/Trailing slash can break strict matching on some proxies
https://myhome.example.com/api/mcpCorrect form

Cause 5: Nothing is exposed

Even a perfect connection is useless if no entities are exposed. Open the voice assistants settings in Home Assistant and expose the lights, switches, climate devices and scenes you want the assistant to see. Begin with five to ten entities. A giant list slows responses and raises the risk of the model picking the wrong device.

A woman in a denim shirt smiling at her phone in a bright kitchen while a pendant light turns on

A Step by Step Fix Checklist

Work through this in order. Stop as soon as something starts working.

  1. Confirm the integration is on. In Home Assistant, add the Model Context Protocol Server integration and check that it loads without errors.
  2. Confirm exposure. Make sure at least one entity is exposed to the assistant.
  3. Confirm the external URL. Settings, System, Network. Use the same HTTPS address you plan to give ChatGPT.
  4. Test from outside. Mobile data, no VPN, load the login page.
  5. Check the proxy headers. If you use any proxy or tunnel, add it to trusted_proxies.
  6. Remove old connectors. Delete failed attempts in ChatGPT before adding a new one.
  7. Add the connector. Paste the full /api/mcp URL and choose OAuth.
  8. Test with a read-only question. Then try a harmless action, like a single lamp.
  9. Read the logs. If something still fails, the Home Assistant log and your proxy log usually name the real culprit.

A developer in a home office reading logs on two monitors in evening light

Reading the logs without losing an evening

Logs are noisy. A practical trick: copy the ten lines around the failed connection attempt, remove any tokens or personal addresses, and paste them into a chat model for a plain language explanation. On PicassoIA you can do that with GPT-4o, Claude Sonnet 5 or Gemini 3.5 Flash. For longer proxy configurations, GPT 5.6 Sol handles code-heavy tasks well. Always strip secrets first.

Remote Access Without Paying

Here is the part most tutorials gloss over. The cleanest path is Home Assistant Cloud from Nabu Casa. It handles the public HTTPS address and certificates for you, and your external URL is detected automatically. It is also a paid subscription, and it supports the project's development, so it is a fair choice if you want the least effort.

But you asked about a free setup, so let's look at what actually works at zero monthly cost.

Top-down view of a workbench with a small single board computer, SSD, cables and a notebook with a network sketch

Option A: A free tunnel service

A tunnel makes an outbound connection from your home to a provider, which then forwards public HTTPS traffic back to you. You do not open any router port.

What you need:

  • A domain name (a domain is the only unavoidable small cost, often a few dollars per year) or a free subdomain from some providers.
  • The tunnel add-on or container running next to Home Assistant.
  • Your proxy added to trusted_proxies.

Pros: no port forwarding, works behind carrier grade NAT, certificates are handled for you.

Cons: you depend on a third party, and some tunnel features change their free tier terms.

Option B: Dynamic DNS plus port forwarding

The classic route. A free dynamic DNS name points to your home IP, your router forwards port 443 to a reverse proxy, and the proxy gets a free certificate from Let's Encrypt.

Pros: fully under your control, no recurring fees.

Cons: needs a public IP (not behind carrier grade NAT), exposes a port, and demands you keep the proxy updated.

Option C: A public funnel through a mesh VPN

Some mesh VPN tools can publish a service to the public internet over HTTPS on a generated address, while the rest of your devices stay private. Setup is short, but the generated address is fixed by the provider, so check that OAuth discovery still passes with that hostname.

Which free option fits you

SituationBest fitEffort
Behind carrier grade NAT or shared building internetTunnel serviceLow
Home internet with a real public IP and some networking comfortDynamic DNS and reverse proxyMedium
You want the quickest testMesh VPN funnelLow
You want zero maintenanceHome Assistant Cloud (paid)Lowest

💡 Test before you commit. Whatever you pick, confirm that the page https://your-address/api/mcp answers from mobile data before touching ChatGPT. It saves an hour of guessing.

A young man on a train platform at dusk checking his phone

The Webhook Proxy Route

Some community projects, such as the ha-mcp add-on, take a different route from the built-in integration. They run their own MCP server and expose it either through a secret URL or through a webhook proxy. For Nabu Casa users, the proxy produces an address shaped like https://xxxxx.ui.nabu.casa/api/webhook/mcp_xxxxxxxx.

If you go this way, three details matter:

  • Copy the full URL from the add-on log. A mistyped or regenerated secret is a common reason for failure.
  • Treat the URL like a password. Anyone holding it may be able to reach your tools.
  • Regenerate it if it leaks. Then update the connector.

This path is useful if the built-in OAuth flow keeps failing in your setup. The tradeoff is that you rely on a third party add-on, so read what it exposes before turning it on.

Keep It Safe

Giving a cloud chatbot the power to flip switches deserves some caution. A few rules keep the risk small.

A brass padlock on a weathered wooden garden gate with ivy and morning light

Expose less than you think

Do not expose door locks, garage doors, alarm panels or anything that opens your home to a stranger. Start with lights, climate and media. Add more only when you trust the behavior.

Use a dedicated user

Create a separate Home Assistant user for the assistant if your setup allows it, so you can revoke access in one click without touching your own login.

Watch the activity

Check the logbook after the first sessions. You will see exactly which services the assistant called. If something surprises you, narrow the exposed list.

Keep software updated

Both Home Assistant and any proxy or tunnel add-on receive security patches. A public address makes updates more important, not less.

Never paste secrets into a chat

Long-lived access tokens, webhook URLs and passwords do not belong in prompts. If you share config for troubleshooting, replace them with placeholders.

What You Can Do Once It Works

When the connection finally holds, the fun starts. Here are requests that work well with a modest set of exposed entities:

  • "Turn off every light downstairs except the hallway."
  • "Is anything left on in the kitchen?"
  • "Set the bedroom thermostat to 19 degrees and tell me the current reading."
  • "Run the movie scene."
  • "Which windows are open right now?"

A hand pressing a plain white wall light switch with a warm lamp lit in the background

Write better entity names

The model picks devices by name. "Light 3" is a bad name. "Living room reading lamp" is a good one. Spend twenty minutes renaming entities and areas, and accuracy jumps noticeably. Assign every device to an area so a sentence like "turn off the lights in the bedroom" has something to match.

Use scripts and scenes as shortcuts

Instead of making the assistant compose five separate actions, wrap them in a script or scene. "Good night" becomes a single call that locks the logic you trust: lights off, thermostat down, media paused. Fewer calls mean fewer chances for a misstep.

Ask for state before action

A habit that prevents surprises: ask what is on before asking to switch things off. It confirms the connection is live and the entity names match what you expect.

A couple relaxing on a sofa in the evening with a laptop, a lit lamp and a cat on a blanket

Still Stuck? Quick Diagnosis Table

SymptomMost likely causeTry this
Spinner forever when adding the connectorServer unreachable from the internetTest the URL on mobile data
"Failed to resolve OAuth client"Proxy, domain or external URL mismatchAlign external URL, add trusted proxies, re-add connector
Login works, no tools listedNo entities exposedExpose a few entities in voice assistant settings
Tools listed, actions refusedPlan, mode or blocked tool callsTry a read-only request, fresh chat, check connector settings
Works for a day, then stopsChanged IP, expired tunnel or regenerated secretCheck dynamic DNS, tunnel status and the add-on log
Wrong device switchedVague entity namesRename entities and assign areas
404 on the connector URLWrong pathUse the /api/mcp path

Which Assistant Should You Pair It With

ChatGPT is not the only assistant that can talk to an MCP server. If you want a second opinion or a backup when one service has an outage, other chat models are worth keeping nearby for config help, YAML writing and log reading. On PicassoIA you can compare Claude Fable 5 for coding tasks, Gemini 3.1 Pro for general answers, DeepSeek V3.1 for budget friendly reasoning, and GPT 5.6 Luna for quick replies. These are handy for drafting automations, converting a rough idea into a clean script, or turning a confusing log into plain English. They do not connect to your Home Assistant by themselves here, but they make the troubleshooting side far faster.

💡 Prompt that works well for config help: "Here is my Home Assistant http: section and the error from the connector. Explain what is mismatched and show a corrected version. Use placeholders for any address or token."

Try It Yourself on Picasso IA

Getting a chatbot to run your home is a satisfying project, and the same curiosity pays off in other places. If you enjoy the troubleshooting side, open the Picasso IA language models and try pasting a log, drafting an automation or asking for a clean explanation of a proxy setting. Then go further: generate images, short clips, voiceovers or music with the other tools on the platform. Pick a model, write a prompt, and see what comes back. Your next experiment is one prompt away.

Share this article

Choose your language

FreeCreate AI Images and VideosFree, No Credit CardFree Generations to StartSeedance 2.5 Lite IncludedStart Free Now