From 774125a5ee5419b704c9af635e65e92a3568b108 Mon Sep 17 00:00:00 2001
From: Mike Cao <mike@umami.is>
Date: Fri, 4 Sep 2026 23:31:57 -0700
Subject: [PATCH] Support CommonJS imports and clarify Cloud MCP authentication
 setup

---
 packages/api-client/package.json |  8 ++++++--
 packages/mcp/README.md           | 32 ++++++++++++++++++++++++++++++--
 2 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/packages/api-client/package.json b/packages/api-client/package.json
index e7d2ca2ab..41308fcc9 100644
--- a/packages/api-client/package.json
+++ b/packages/api-client/package.json
@@ -10,10 +10,14 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     }
   },
-  "files": ["dist", "README.md"],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsup",
     "test": "vitest run",
diff --git a/packages/mcp/README.md b/packages/mcp/README.md
index 55a3d9ca7..01a46d37f 100644
--- a/packages/mcp/README.md
+++ b/packages/mcp/README.md
@@ -27,12 +27,26 @@ user/team permission checks as the web app.
 
 All tools are read-only. Dates are ISO 8601; results are paginated with a hard cap on page size.
 
-## Remote (Umami Cloud / self-hosted with OAuth)
+## Remote: Umami Cloud
+
+Connect to `https://cloud.umami.is/mcp` using your existing Cloud API key:
+
+```text
+Authorization: Bearer api_<your-cloud-api-key>
+```
+
+Clients that support custom headers may use `x-umami-api-key` instead. If both headers are
+provided, they must contain the same key. Use a client that supports API-key or bearer-header
+configuration; Cloud OAuth discovery is not implemented by this endpoint.
+
+Cloud MCP has the same subscription requirements and website/team permissions as the Cloud API.
+All tools call the Cloud API gateway, which validates the key and routes requests to your region.
+
+## Remote: self-hosted with OAuth
 
 Add the MCP endpoint to your client:
 
 ```text
-https://cloud.umami.is/mcp
 https://your-umami.example.com/mcp
 ```
 
@@ -67,6 +81,20 @@ Self-hosted instances can alternatively pass an API key (`umami_…`) as the bea
 | `UMAMI_API_TOKEN` | API key or login token (self-hosted).                              |
 | `UMAMI_API_KEY`   | Umami Cloud API key.                                               |
 
+For Cloud stdio, set `UMAMI_API_KEY` and omit `UMAMI_URL` and `UMAMI_API_TOKEN`:
+
+```json
+{
+  "mcpServers": {
+    "umami": {
+      "command": "npx",
+      "args": ["-y", "@umami/mcp"],
+      "env": { "UMAMI_API_KEY": "api_<your-cloud-api-key>" }
+    }
+  }
+}
+```
+
 ## Example prompts
 
 - Show my websites.