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.

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:
- You enable the MCP server integration in Home Assistant.
- You decide which entities the assistant may see, using the Assist exposure settings.
- You paste the server URL into ChatGPT as a custom connector and choose OAuth as the authentication method.
- 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 type | Where the request comes from | Needs public access? |
|---|
| Desktop app on your home network | Your own computer | Usually no |
| ChatGPT on the website | OpenAI servers | Yes |
| Mobile app on mobile data | Cloud or phone, outside your LAN | Yes |
| Local script or agent | Same network | No |
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.

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 pasted | Problem |
|---|
http://homeassistant.local:8123/api/mcp | Local only, and not HTTPS |
https://myhome.example.com | Missing the MCP path |
https://myhome.example.com/api/mcp/ | Trailing slash can break strict matching on some proxies |
https://myhome.example.com/api/mcp | Correct 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 Step by Step Fix Checklist
Work through this in order. Stop as soon as something starts working.
- Confirm the integration is on. In Home Assistant, add the Model Context Protocol Server integration and check that it loads without errors.
- Confirm exposure. Make sure at least one entity is exposed to the assistant.
- Confirm the external URL. Settings, System, Network. Use the same HTTPS address you plan to give ChatGPT.
- Test from outside. Mobile data, no VPN, load the login page.
- Check the proxy headers. If you use any proxy or tunnel, add it to
trusted_proxies.
- Remove old connectors. Delete failed attempts in ChatGPT before adding a new one.
- Add the connector. Paste the full
/api/mcp URL and choose OAuth.
- Test with a read-only question. Then try a harmless action, like a single lamp.
- Read the logs. If something still fails, the Home Assistant log and your proxy log usually name the real culprit.

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.

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
| Situation | Best fit | Effort |
|---|
| Behind carrier grade NAT or shared building internet | Tunnel service | Low |
| Home internet with a real public IP and some networking comfort | Dynamic DNS and reverse proxy | Medium |
| You want the quickest test | Mesh VPN funnel | Low |
| You want zero maintenance | Home 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.

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.

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?"

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.

Still Stuck? Quick Diagnosis Table
| Symptom | Most likely cause | Try this |
|---|
| Spinner forever when adding the connector | Server unreachable from the internet | Test the URL on mobile data |
| "Failed to resolve OAuth client" | Proxy, domain or external URL mismatch | Align external URL, add trusted proxies, re-add connector |
| Login works, no tools listed | No entities exposed | Expose a few entities in voice assistant settings |
| Tools listed, actions refused | Plan, mode or blocked tool calls | Try a read-only request, fresh chat, check connector settings |
| Works for a day, then stops | Changed IP, expired tunnel or regenerated secret | Check dynamic DNS, tunnel status and the add-on log |
| Wrong device switched | Vague entity names | Rename entities and assign areas |
| 404 on the connector URL | Wrong path | Use 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.