Clarify URL configuration for MCP server#45663
Conversation
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds guidance to the MCP Server integration docs to prevent OAuth login failures when configuring Claude for Desktop with a remote custom connector by clarifying which Home Assistant URL must be used.
Changes:
- Adds a documentation note instructing users to use the configured Home Assistant external URL (including Nabu Casa Cloud URL where applicable).
- Explains why using alternate/internal URLs can break OAuth redirect behavior (blank 404 during login).
- Points users to the UI location to verify/update the external URL setting.
| When using a remote custom connector in Claude for Desktop, the connection is brokered through Anthropic's cloud infrastructure. This means your Home Assistant instance must be publicly accessible from the internet. | ||
|
|
||
| {% note %} | ||
| Use the same URL that is configured as your Home Assistant external URL. If you use [Home Assistant Cloud](/integrations/cloud/), use your Nabu Casa Cloud URL (for example, `https://<your_id>.ui.nabu.casa`). Connecting with a different URL, such as an internal split-horizon domain, can cause the login step to fail with a blank 404 page, because Home Assistant builds the OAuth redirect from the configured external URL. You can check or update this URL at {% my network title="**Settings** > **System** > **Network**" %}. |
There was a problem hiding this comment.
So above we say "This means your Home Assistant instance must be publicly accessible from the internet". and below we says <your_home_assistant_external_url>.
Perhaps we can edit one of these points and link to https://www.home-assistant.io/docs/configuration/remote/ if users don't know what their external URL is?
c0ffeeca7
left a comment
c0ffeeca7
left a comment
There was a problem hiding this comment.
I'm drafting this PR, as changes are needed. https://github.com/home-assistant/home-assistant.io/pull/45663/changes#r3331042642
Please undraft it once the changes have been implemented and the PR is ready for review again.
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
Proposed change
This PR adds a note to clarify where to get the Home Assistant URL from. If you're using a custom domain with Home Assistant Cloud, that won't work for the authorisation from something like Claude. You need to use the URL specified from Home Assistant Cloud/what is configured within your Home Assistant instance.
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.