diff --git a/packages/docs/mcp-server.mdx b/packages/docs/mcp-server.mdx
index 507b101f99..dfd3b5d409 100644
--- a/packages/docs/mcp-server.mdx
+++ b/packages/docs/mcp-server.mdx
@@ -56,6 +56,12 @@ The `npx -y @trycompai/mcp-server` command you'll see throughout is what handles
 
 No JSON editing required.
 
+<Warning>
+The drag-and-drop installer is configured for the hosted Comp AI service.
+
+If you're using a self-hosted deployment, use the manual JSON configuration and include the `--server-url` argument.
+</Warning>
+
 <Accordion title="Advanced — manual JSON config">
 If you prefer to manage `claude_desktop_config.json` yourself, open **Settings → Developer → Edit Config** and merge:
 
@@ -89,6 +95,12 @@ Fully quit and reopen Claude Desktop.
 
 Click the button above, confirm in Cursor, then paste your Comp AI API key when prompted.
 
+<Warning>
+The one-click installer is configured for the hosted Comp AI service.
+
+If you're using a self-hosted deployment, use the Advanced — manual JSON config below and include the `--server-url` argument.
+</Warning>
+
 <Accordion title="Advanced — manual JSON config">
 Open **Cursor → Settings → Tools and Integrations → New MCP Server** and paste:
 
@@ -118,6 +130,12 @@ Save and reload Cursor.
 
 Click the button above, confirm in VS Code, then paste your Comp AI API key when prompted.
 
+<Warning>
+The one-click installer is configured for the hosted Comp AI service.
+
+If you're using a self-hosted deployment, use the Advanced — manual JSON config below and include the `--server-url` argument.
+</Warning>
+
 <Accordion title="Advanced — manual JSON config">
 Open the **Command Palette → MCP: Open User Configuration** and paste:
 
@@ -200,6 +218,139 @@ Save and reload Windsurf.
 
 </Tabs>
 
+## Self-hosted deployments
+
+If you're connecting to a self-hosted Comp AI deployment instead of the hosted Comp AI service, you must include the `--server-url` argument in your MCP server configuration.
+
+Hosted Comp AI users do not need to specify `--server-url`.
+
+Choose your AI client below and update its configuration by adding the `--server-url` argument.
+
+<Tabs>
+
+<Tab title="Claude Desktop">
+
+Update the manual JSON configuration by adding the `--server-url` argument.
+
+```json
+{
+  "mcpServers": {
+    "comp-ai": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@trycompai/mcp-server",
+        "start",
+        "--apikey",
+        "comp_your_api_key_here",
+        "--server-url",
+        "https://your-self-hosted-comp-api.example.com"
+      ]
+    }
+  }
+}
+```
+</Tab>
+
+<Tab title="Cursor">
+
+Update the manual JSON configuration by adding the `--server-url` argument.
+
+```json
+{
+  "command": "npx",
+  "args": [
+    "-y",
+    "@trycompai/mcp-server",
+    "start",
+    "--apikey",
+    "comp_your_api_key_here",
+    "--server-url",
+    "https://your-self-hosted-comp-api.example.com"
+  ]
+}
+```
+</Tab>
+
+<Tab title="VS Code">
+
+Update your MCP configuration by adding the `--server-url` argument.
+
+```json
+{
+  "command": "npx",
+  "args": [
+    "-y",
+    "@trycompai/mcp-server",
+    "start",
+    "--apikey",
+    "comp_your_api_key_here",
+    "--server-url",
+    "https://your-self-hosted-comp-api.example.com"
+  ]
+}
+```
+</Tab>
+
+<Tab title="Claude Code (CLI)">
+
+Append the `--server-url` argument to your existing installation command.
+
+```bash
+claude mcp add CompAI -- npx -y @trycompai/mcp-server start \
+  --apikey comp_your_api_key_here \
+  --server-url https://your-self-hosted-comp-api.example.com
+```
+</Tab>
+
+<Tab title="Codex CLI">
+
+Append the `--server-url` argument to your existing installation command.
+
+```bash
+codex mcp add comp-ai -- npx -y @trycompai/mcp-server start \
+  --apikey comp_your_api_key_here \
+  --server-url https://your-self-hosted-comp-api.example.com
+```
+</Tab>
+
+<Tab title="Gemini CLI">
+
+Append the `--server-url` argument to your existing installation command.
+
+```bash
+gemini mcp add CompAI -- npx -y @trycompai/mcp-server start \
+  --apikey comp_your_api_key_here \
+  --server-url https://your-self-hosted-comp-api.example.com
+```
+</Tab>
+
+<Tab title="Windsurf">
+
+Update your MCP configuration by adding the `--server-url` argument.
+
+```json
+{
+  "mcpServers": {
+    "comp-ai": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@trycompai/mcp-server",
+        "start",
+        "--apikey",
+        "comp_your_api_key_here",
+        "--server-url",
+        "https://your-self-hosted-comp-api.example.com"
+      ]
+    }
+  }
+}
+```
+</Tab>
+
+</Tabs>
+
 That's it. The first time you start a chat in your AI client after install, the assistant will discover the Comp AI tools and start using them.
 
 ## Verify it worked