diff --git a/docs/configuration/tools/index.md b/docs/configuration/tools/index.md
index 57e683e445..773df257bf 100644
--- a/docs/configuration/tools/index.md
+++ b/docs/configuration/tools/index.md
@@ -131,7 +131,7 @@ toolsets:
 | ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
 | `remote.url`            | string  | URL of the MCP server. Accepts `https://`, `http://`, and `unix://` (Unix domain socket) schemes.                     |
 | `remote.transport_type` | string  | `streamable` or `sse`                                                                                                 |
-| `remote.headers`        | object  | HTTP headers (typically for auth)                                                                                     |
+| `remote.headers`        | object  | HTTP headers sent on every request. Values support `${env.VAR}` and `${headers.NAME}` placeholders, resolved per request. `${env.VAR}` reads an environment variable; `${headers.NAME}` forwards a header from the caller's incoming request (useful when docker-agent runs as an API server). |
 | `allow_private_ips`     | boolean | Permit remote MCP OAuth helper requests to dial non-public IP addresses. Use only for trusted internal servers.        |
 
 ## Auto-Installing Tools
diff --git a/docs/features/remote-mcp/index.md b/docs/features/remote-mcp/index.md
index dbf7743365..2de5640871 100644
--- a/docs/features/remote-mcp/index.md
+++ b/docs/features/remote-mcp/index.md
@@ -53,7 +53,7 @@ toolsets:
       url: "https://mcp.example.com/mcp"
       transport_type: "streamable" # or "sse" for legacy servers
       headers:
-        Authorization: "Bearer token" # optional: static auth
+        Authorization: "Bearer ${env.MY_TOKEN}" # resolved per request
     # Optional: use only for trusted internal/private MCP or OAuth endpoints.
     allow_private_ips: true
 ```
@@ -67,6 +67,14 @@ Set `allow_private_ips: true` on a remote MCP toolset only when the MCP server o
 >
 > Configured `headers` are forwarded to OAuth protected-resource-metadata discovery requests directed at the MCP server's own host — not to third-party authorization servers. This allows services like Grafana Cloud that require a routing header (e.g. `X-Grafana-URL`) on the discovery request to scope the OAuth flow correctly. Headers are never sent to a different host than the one in `remote.url`.
 
+> [!NOTE]
+> **Per-request header template expansion**
+>
+> Header values in `remote.headers` support `${env.VAR}` and `${headers.NAME}` placeholders. Both are resolved on every outbound HTTP request (not just once at initialization), so short-lived credentials and forwarded caller headers always reflect the latest values:
+>
+> - `${env.VAR}` — reads the named environment variable. Useful for credentials stored in a secret manager that rotates them in-process.
+> - `${headers.NAME}` — forwards the named header from the caller's incoming HTTP request. Only meaningful when docker-agent is running as an API server (`docker agent serve api`) and a client passes authentication headers that the upstream MCP server also accepts.
+
 > [!NOTE]
 > **Automatic reconnection after idle timeouts**
 >
@@ -86,7 +94,10 @@ Set `allow_private_ips: true` on a remote MCP toolset only when the MCP server o
 
 Most remote MCP servers that require OAuth support [Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591) — no configuration is needed, docker-agent handles the flow for you.
 
-For servers that do **not** support DCR, provide explicit OAuth credentials with the `oauth:` block:
+For servers that do **not** support DCR, docker-agent falls back automatically:
+
+1. **Interactive credential prompt**: docker-agent presents a dialog asking for your `client_id` (required) and optionally a `client_secret`. This covers servers that require pre-registered app credentials but don't advertise them via DCR.
+2. **Explicit `oauth:` block** (recommended when you know the credentials in advance): add the block described below to skip the interactive prompt and supply credentials directly in config.
 
 ```yaml
 toolsets:
diff --git a/docs/tools/mcp/index.md b/docs/tools/mcp/index.md
index 510bc83112..0b60da5193 100644
--- a/docs/tools/mcp/index.md
+++ b/docs/tools/mcp/index.md
@@ -99,12 +99,33 @@ toolsets:
 | ----------------------- | ------- | ----------- |
 | `remote.url`            | string  | Base URL of the MCP server. |
 | `remote.transport_type` | string  | `streamable` or `sse`. |
-| `remote.headers`        | object  | HTTP headers (typically for static auth tokens). |
+| `remote.headers`        | object  | HTTP headers sent on every request. Values support `${env.VAR}` and `${headers.NAME}` placeholders, resolved per request. See [Remote MCP Servers](../../features/remote-mcp/index.md#per-request-header-template-expansion) for details. |
 | `remote.oauth`          | object  | Explicit OAuth client credentials for servers that don't support DCR. See [Remote MCP Servers](../../features/remote-mcp/index.md#oauth-for-servers-without-dynamic-client-registration). |
 | `allow_private_ips`     | boolean | Permit remote MCP OAuth helper requests to dial non-public IP addresses. Use only for trusted internal servers. |
 
 For a curated list of public remote MCP endpoints (Linear, GitHub, Vercel, Notion, …) and full OAuth configuration details, see [Remote MCP Servers](../../features/remote-mcp/index.md).
 
+## MCP Prompts
+
+MCP servers can expose **prompts** — named, parameterized templates that the server provides via the `/prompts` endpoint. Docker Agent discovers these at toolset startup and registers them as **slash commands** in the TUI, so you can invoke them directly from the input box.
+
+```text
+# Type / to see available prompts alongside built-in commands
+/review         # invoke an MCP prompt named "review"
+/summarize My text here   # invoke with the first argument filled in
+```
+
+**How it works:**
+
+- Each MCP prompt appears in the command palette (accessible via <kbd>Ctrl</kbd>+<kbd>K</kbd>) under the **MCP Prompts** category.
+- Typing `/<prompt-name>` in the input box invokes the prompt immediately.
+- If the prompt declares arguments and you provide text after the slash command, that text is mapped to the first declared argument.
+- If a required argument is missing, docker-agent opens the argument input dialog before running the prompt.
+- When no argument is needed or all required arguments are supplied, the prompt runs immediately.
+
+> [!NOTE]
+> MCP prompt discovery requires a YAML-declared `mcp` toolset. Prompts from servers activated through the [Docker MCP Catalog](../../tools/mcp-catalog/index.md) (`ref: docker:<name>`) are not currently surfaced.
+
 ## Embedded Resources
 
 MCP tool results can include embedded resources — images, PDFs, and text files returned directly in the tool response. Docker Agent preserves these as attachments and forwards them to the model as native content blocks: