Add documentation for Model Context Protocol Server integration

source/_integrations/mcp_server.markdown

@@ -0,0 +1,199 @@
+---
+title: Model Context Protocol Server
+description: Instructions on how to add a Model Context Protocol Server to Home Assistant.
+ha_category:
+  - Voice
+ha_release: 2025.2
+ha_iot_class: Local Push
+ha_config_flow: true
+ha_codeowners:
+  - 'allenporter'
+ha_domain: mcp_server
+ha_integration_type: integration
+related:
+  - docs: /integrations/conversation/
+    title: Conversation
+---
+
+The [Model Context Protocol](https://modelcontextprotocol.io) is an open protocol for standardizing how applications provide context to LLMs. The **Model Context Protocol Server** integration enables using Home Assistant as context for MCP LLM Client Applications.
+
+This integration can help you expose other Home Assistant integrations as
+context for LLM applications outside of Home Assistant. For example, you can expose
+your Google Tasks To-do list as a tool for Claude Desktop.
+
+Controlling Home Assistant is done by providing MCP clients access to the Assist API of Home Assistant. You can control what devices and entities it can access from the {% my voice_assistants title="exposed entities page" %}.
+
+## Pre-requisites
+
+1. You will need an [MCP client ](https://modelcontextprotocol.io/clients) LLM Application such as [Claude Desktop](https://claude.ai/download).
+1. Since most clients do not support native remote servers, you will need an additional local MCP server  remote gateway.
+
+See [Client Configuration](#client-configuration) below for detailed instructions.
+
+{% include integrations/config_flow.md %}
+
+## Configuration options
+
+The integration provides the following configuration options:
+
+{% configuration_basic %}
+Control Home Assistant:
+  description: The API to use to expose tools over the Model Context Protocol. Clients
+    can only control or provide information about entities that are [exposed](/voice_control/voice_remote_expose_devices/) to it.
+{% endconfiguration_basic %}
+
+## Architecture Overview
+
+This integration can provide similar functionality as other LLM based conversation
+agents (for example [Anthropic](/integrations/anthropic/), [Google Generative AI](/integrations/google_generative_ai_conversation), [Ollama](/integrations/ollama/), [Open AI](/integrations/openai_conversation/)). In those conversation agents, Home Assistant is the
+client and prepares the available tools and passes them into the LLM with a prompt.
+
+The Model Context Protocol follows a different pattern: An LLM application acts as
+a client and can connect to multiple MCP servers to provide context. See the
+[Model Context Protocol Introduction](https://modelcontextprotocol.io/introduction#general-architecture) for more details.
+
+The Home Assistant Model Context Protocol Server integration implements the
+[Server-Sent Events (SSE) transport](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse)
+allowing streaming client-to-server communication. Most MCP clients today only support
+[stdio](https://modelcontextprotocol.io/docs/concepts/transports#standard-input-output-stdio) transport,
+and directly run an MCP server as a local command line tool. You can 
+use an MCP proxy server like [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy)
+to act as a gateway to the Home Assistant MCP SSE server.
+
+## Client Configuration
+
+The Model Context Protocol specification does not yet currently define standards
+for authentication and connecting to remote servers. These are a *work in progress*
+and this configuration will likely change in the near future.
+
+### Access Control
+
+For now, we can use
+[Long-lived access token](https://developers.home-assistant.io/docs/auth_api/#long-lived-access-token) to control access to the API.
+
+1. Visit your account profile settings, under the **Security** tab. {% my profile badge %}.
+
+1. Create a **Long-lived access token**
+
+1. Copy the access token to use when configuring the MCP client LLM application.
+
+See [Authentication](https://www.home-assistant.io/docs/authentication/#your-account-profile) for more information about Authentication in Home Assistant.
+
+### Example: Claude for Desktop
+
+See [MCP Quickstart: For Claude Desktop Users](https://modelcontextprotocol.io/quickstart/user#for-claude-desktop-users)
+for a detailed guide on using Claude Desktop with an MCP server. It is recommended
+to get the example server working first before using the Home Assistant MCP Server.
+
+Claude for Desktop currently only supports local MCP servers. These are called [stdio](https://modelcontextprotocol.io/docs/concepts/transports#standard-input-output-stdio)
+servers that are run as a local service by Claude for Desktop. We use a local proxy MCP server
+to allow Claude to communicate with Home Assistant.
+
+1. Download [Claude for Desktop](https://claude.ai/download). 
+
+1. Install `mcp-proxy` following the instructions in the [README](https://github.com/sparfenyuk/mcp-proxy).
+   For example, `uv tool install git+https://github.com/sparfenyuk/mcp-proxy`
+
+1. Open the configuration file. Visit *Settings…* and *Developer* tab the click *Edit Config*
+   which will edit `claude_desktop_config.json`. The full file location depends on your
+   operating system macOS or Windows.
+
+1. Add a new MCP server to json file. You will need to set the `SSE_URL` to the local url to your
+   Home Assistant instance with the path `/mcp_server/sse`. You will also need to set `API_ACCESS_TOKEN`
+   to the long live access token created above in the [access control instructions](#access-control)
+
+  ```json
+  {
+    "mcpServers": {
+      "home-assistant": {
+        "command": "mcp-proxy",
+        "env": {
+          "SSE_URL": "http://localhost:8123/mcp_server/sse",
+          "API_ACCESS_TOKEN": "eyJhbGciOiJIUzI1NiIsInR5cCI...."
+        }
+      }
+    }
+  }
+  ```
+
+1. Restart Claude
+
+1. You will see a connection icon {% icon "mdi:connection" %} if things are set up correctly. Clicking the connection icon will show enabled MCP servers such as Home Assistant `home-assistant`.
+
+1. You can then use Claude to control Home Assistant similar to how you control Home Assistant through the Voice Assistant. Claude wil ask you for permission before calling any tools.
+
+  ![Screenshot of Claude Desktop adding an item to a Home Assistant To-do list](/images/integrations/nest/claude-todo-list-control.png)
+
+
+## Supported functionality
+
+### Prompts
+
+[MCP Prompts](https://modelcontextprotocol.io/docs/concepts/prompts) are reusable
+workflows that clients can surface. The prompt used by the LLM API are exposed.
+
+### Tools
+
+[MCP Tools](https://modelcontextprotocol.io/docs/concepts/tools) enable LLMs to
+perform actions through Home Assistant. The tools used by the configured LLM API
+are exposed.
+
+## Known Limitations
+
+The Remote Model Context Protocol integration does not currently support
+notifications which notify clients of state changes.
+
+## Troubleshooting
+
+### LLM client cannot connect to Home Assistant MCP server
+
+#### Symptom: Failed to start MCP server: Could not start MCP server home-assistant
+
+When trying to configure a client like Claude Desktop to talk to Home Assistant, the app shows a
+message like "Failed to start MCP server: Could not start MCP server home-assistant"
+
+##### Description
+
+This means that the local MCP server `mcp-proxy` could not start.
+
+##### Resolution
+
+Verify the command line arguments in the `claude_desktop_config.json` are correct. You may try to run
+the command manually to verify that the command can be found.
+
+#### Symptom: “MCP server home-assistant disconnected” or "Could not attach to MCP server home-assistant"
+
+When trying to configure a client like Claude Desktop to talk to Home Assistant, the app shows a
+message like "MCP server home-assistant disconnected" or "Could not attach to MCP server home-assistant".
+
+##### Description
+
+This means the MCP server has started, however the MCP server is having trouble communicating with Home Assistant,
+or the MCP server in Home Assistant is not configured.
+
+##### Resolution
+
+To understand the root cause, first check debug logs on the client. For example in Claude for Desktop:
+
+1. Visit *Settings...*
+
+1. Click *Developer*
+
+1. Click the `home-assistant` MCP server
+
+1. Click *Open Logs Folder*
+
+1. View `mcp-server-Home-assistant.log`. These are known problems and their resolution:
+
+   -  `Client error '404 Not Found' for url 'http://localhost:8123/mcp_server/sse'`:
+      this means the MCP Server integration is not configured in Home Assistant.
+
+   -  `Client error '401 Unauthorized' for url 'http://localhost:8123/mcp_server/sse'`:
+     this means that the long live access token is not correct.
+...
+
+## Remove integration
+
+This integration can be removed by following these steps:
+
+{% include integrations/remove_device_service.md %}