code · pull · Jan 13, 2026 · Jan 13, 2026 · Jan 13, 2026
diff --git a/docs/pages/product/apis-integrations/core-data-apis/rest-api/reference.mdx b/docs/pages/product/apis-integrations/core-data-apis/rest-api/reference.mdx
@@ -29,6 +29,7 @@ Response
   - `title` - Human readable title from the data model.
   - `shortTitle` - Short title for visualization usage (ex. chart overlay)
   - `type` - Data type
+- `lastRefreshTime` - An ISO 8601 timestamp indicating when the data was last refreshed.
 - `total` - The total number of rows returned for the query. Useful for
   paginating results.
 
@@ -68,6 +69,7 @@ Example response:
       "users.count": "700"
     }
   ],
+  "lastRefreshTime": "2025-01-13T12:00:00.000Z",
   "annotation": {
     "measures": {
       "users.count": {
@@ -327,9 +329,10 @@ This endpoint is part of the [SQL API][ref-sql-api].
 | `cache` | See [cache control][ref-cache-control]. `stale-if-slow` by default | ❌ No |
 
 Response: a stream of newline-delimited JSON objects. The first object contains
-the `schema` property with column names and types. The following objects contain
-chunks of the result set under the `data` property. Each chunk includes one or more
-rows of the result set.
+the `schema` property with column names and types, and optionally
+`lastRefreshTime` indicating when the data was last refreshed.
+The following objects contain chunks of the result set under the `data` property.
+Each chunk includes one or more rows of the result set.
 
 ### Example
 
@@ -347,7 +350,7 @@ curl \
 Response:
 
 ```json
-{"schema":[{"name":"value","column_type":"Int64"}]}
+{"schema":[{"name":"value","column_type":"Int64"}],"lastRefreshTime":"2025-01-13T12:00:00.000Z"}
 {"data":[["789"]]}
 {"data":[["123"]]}
 {"data":[["456"]]}
@@ -367,7 +370,7 @@ curl \
 Response:
 
 ```json
-{"schema":[{"name":"full_name","column_type":"String"},{"name":"wins","column_type":"Int64"},{"name":"avg_position","column_type":"Double"}]}
+{"schema":[{"name":"full_name","column_type":"String"},{"name":"wins","column_type":"Int64"},{"name":"avg_position","column_type":"Double"}],"lastRefreshTime":"2025-01-13T12:00:00.000Z"}
 {"data":[["Max VERSTAPPEN","10","3.730769230769231"],["Lando NORRIS","4","4"],["Charles LECLERC","4","4.730769230769231"],["Oscar PIASTRI","3","4.8076923076923075"],["Andrea Kimi ANTONELLI","0","5"]]}
 ```
 

diff --git a/docs/pages/product/apis-integrations/embed-apis/chat-api.mdx b/docs/pages/product/apis-integrations/embed-apis/chat-api.mdx
@@ -82,7 +82,7 @@ while (true) {
 | `input` | string | No | The user's message or question. If omitted returns current state of thread with provided chatId. |
 | `chatId` | string | No | Chat thread ID. If omitted, a new thread is created automatically. If provided, it should match the previously returned `chatId` from a message with id `__cutoff__` sent as the `state.chatId` field. |
 | `sessionSettings.externalId` | string | No | Unique identifier for the external user, lowercase and without spaces. Either `externalId` or `internalId` should be provided. |
-| `sessionSettings.internalId` | string | No | Email of an internal Cube Cloud user. Either `externalId` or `internalId` should be provided. |
+| `sessionSettings.internalId` | string | No | Email address (or LDAP identifier if account is configured to use LDAP) of an internal Cube Cloud user. Either `externalId` or `internalId` should be provided. |
 | `sessionSettings.email` | string | No | User's email address |
 | `sessionSettings.userAttributes` | array | No | Array of `{name, value}` pairs for row-level security. Not allowed with `internalId`. |
 | `sessionSettings.groups` | string[] | No | Array of group names the user belongs to. Not allowed with `internalId`. |
@@ -104,7 +104,7 @@ User attributes must first be configured in your Cube admin panel before they ca
 
 **Supported Fields:**
 - `externalId` (optional): Unique identifier for the external user. Either `externalId` or `internalId` should be provided.
-- `internalId` (optional): Email of an internal Cube Cloud user. The user must already exist. Either `externalId` or `internalId` should be provided.
+- `internalId` (optional): Email address (or LDAP identifier if account is configured to use LDAP) of an internal Cube Cloud user. The user must already exist. Either `externalId` or `internalId` should be provided.
 - `email` (optional): User's email address  
 - `userAttributes` (optional): Array of key-value pairs containing user metadata. Only available with `externalId`.
 
@@ -155,7 +155,7 @@ Copy the complete Chat API URL from your agent settings (**Chat API URL** field)
 - **`chatId`** (string): Chat thread ID. If omitted, a new thread is created automatically. If provided, it should match the previously returned `chatId` from a message with id `__cutoff__`.
 - **`sessionSettings`** (object, required): Session configuration for the user
   - **`externalId`** (string): Unique identifier for the external user. Either `externalId` or `internalId` should be provided.
-  - **`internalId`** (string): Email of an internal Cube Cloud user. The user must already exist. Either `externalId` or `internalId` should be provided.
+  - **`internalId`** (string): Email address (or LDAP identifier if account is configured to use LDAP) of an internal Cube Cloud user. The user must already exist. Either `externalId` or `internalId` should be provided.
   - **`email`** (string): User's email address
   - **`userAttributes`** (array): Array of `{name, value}` pairs for row-level security. Not allowed with `internalId`.
   - **`groups`** (string[]): Array of group names for user. Not allowed with `internalId`.

diff --git a/docs/pages/product/apis-integrations/embed-apis/generate-session.mdx b/docs/pages/product/apis-integrations/embed-apis/generate-session.mdx
@@ -30,7 +30,7 @@ POST https://{accountName}.cubecloud.dev/api/v1/embed/generate-session
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `externalId` | string | No | Unique identifier for the external user. Either `externalId` or `internalId` should be provided. |
-| `internalId` | string | No | Email of an internal Cube Cloud user. Either `externalId` or `internalId` should be provided. |
+| `internalId` | string | No | Email address (or LDAP identifier if account is configured to use LDAP) of an internal Cube Cloud user. Either `externalId` or `internalId` should be provided. |
 | `userAttributes` | array | No | Array of `{name, value}` pairs for row-level security. Not allowed with `internalId`. |
 | `groups` | string[] | No | Array of group names for user. Not allowed with `internalId`. |
 | `securityContext` | object | No | Custom security context object passed to Cube queries. Not allowed with `internalId`. |

diff --git a/docs/pages/product/apis-integrations/mcp-server.mdx b/docs/pages/product/apis-integrations/mcp-server.mdx
@@ -38,18 +38,37 @@ You'll need three key pieces of information:
 
 #### `CUBE_API_KEY`
 
-- Navigate to <Btn>Admin → Agents → Click on Agent → Enable API Key</Btn>
+- Navigate to <Btn>Admin → API Keys</Btn> to obtain your API key
 
-#### `USER_ID`
+#### User Identity (choose one)
 
-- A unique identifier for the user (e.g., email address or user ID)
-- Used for session settings and personalization
+- **`INTERNAL_USER_ID`**: Email address of an existing Cube user. Use this for internal team members who already have Cube accounts. The user's existing permissions and settings will be used.
+- **`EXTERNAL_USER_ID`**: A unique identifier for external/third-party users (e.g., "user-123", "customer@external.com"). Use this when you need to provide custom user attributes, groups, or row-level security settings.
 
 ## Configuration
 
-
 Add the following configuration to your Claude Desktop or Cursor MCP settings:
 
+### For Internal Cube Users
+
+```json
+{
+  "mcpServers": {
+    "cube-mcp-server": {
+      "command": "npx",
+      "args": ["@cube-dev/mcp-server"],
+      "env": {
+        "CUBE_CHAT_API_URL": "https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state",
+        "CUBE_API_KEY": "your_api_key_here",
+        "INTERNAL_USER_ID": "analyst@yourcompany.com"
+      }
+    }
+  }
+}
+```
+
+### For External Users
+
 ```json
 {
   "mcpServers": {
@@ -59,7 +78,7 @@ Add the following configuration to your Claude Desktop or Cursor MCP settings:
       "env": {
         "CUBE_CHAT_API_URL": "https://ai.{cloudRegion}.cubecloud.dev/api/v1/public/{accountName}/agents/{agentId}/chat/stream-chat-state",
         "CUBE_API_KEY": "your_api_key_here",
-        "USER_ID": "user@example.com"
+        "EXTERNAL_USER_ID": "user-123"
       }
     }
   }
@@ -82,5 +101,10 @@ The server will stream real-time analytics responses with data visualizations an
 
 The MCP server integrates with Cube's [Chat API][ref-chat-api] using API key authentication directly. The Chat API URL should be copied from your agent settings in the Cube admin panel to ensure you're using the correct dynamic endpoint for your deployment.
 
+The server supports two types of user authentication:
+
+- **Internal Users**: Existing Cube users authenticated by their email address. They use their configured permissions and settings from Cube.
+- **External Users**: Third-party users with custom identifiers, allowing for dynamic user attributes, groups, and row-level security configuration.
+
 [ref-api-keys]: /product/administration/workspace/api-keys
 [ref-chat-api]: /product/apis-integrations/embed-apis/chat-api