From 853cba6b0e93c94ec3468a347ba0fe92165677a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Tue, 14 Jul 2026 04:06:44 +0000 Subject: [PATCH 1/2] docs: update docs for PR #3623 - per-request header expansion and OAuth credential fallback for remote MCP --- docs/configuration/tools/index.md | 2 +- docs/features/remote-mcp/index.md | 15 +++++++++++++-- docs/tools/mcp/index.md | 2 +- 3 files changed, 15 insertions(+), 4 deletions(-) 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..a70d91f3ab 100644 --- a/docs/tools/mcp/index.md +++ b/docs/tools/mcp/index.md @@ -99,7 +99,7 @@ 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. | From adc1d3b61278b788cb3206b5288516c7417e7d8d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arnaud=20H=C3=A9ritier?= Date: Tue, 14 Jul 2026 04:07:21 +0000 Subject: [PATCH 2/2] docs: update docs for PR #3565 - MCP prompts available as slash commands in the TUI --- docs/tools/mcp/index.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/tools/mcp/index.md b/docs/tools/mcp/index.md index a70d91f3ab..0b60da5193 100644 --- a/docs/tools/mcp/index.md +++ b/docs/tools/mcp/index.md @@ -105,6 +105,27 @@ toolsets: 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 Ctrl+K) under the **MCP Prompts** category. +- Typing `/` 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:`) 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: