docs: document ${input:...} variable support in MCP server headers and env

CHANGELOG.md

@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Documented `${input:...}` variable support in `headers` and `env` MCP server fields, with runtime support matrix and examples (#343)
+
 ## [0.8.3] - 2026-03-20
 
 ### Added
@@ -49,7 +53,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Harden dependency path validation — reject invalid path segments at parse time, enforce install-path containment, safe deletion wrappers across `uninstall`, `prune`, and `install` (#364)
 
-
 ## [0.8.1] - 2026-03-17
 
 ### Added

docs/src/content/docs/integrations/ide-tool-integration.md

@@ -537,6 +537,32 @@ apm mcp info ghcr.io/github/github-mcp-server
 apm mcp list
 ```
 
+#### `${input:...}` Variables in `headers` and `env`
+
+Values in `headers` and `env` can reference VS Code input variables using `${input:<variable-id>}`. At runtime, VS Code prompts the user for each referenced input before starting the server.
+
+For registry-backed servers, APM auto-generates input prompts from registry metadata. For self-defined servers, APM detects the `${input:...}` patterns in your `apm.yml` and generates matching input definitions.
+
+```yaml
+dependencies:
+  mcp:
+    - name: my-server
+      registry: false
+      transport: http
+      url: https://my-server.example.com/mcp/
+      headers:
+        Authorization: "Bearer ${input:my-server-token}"
+        X-Project: "${input:my-server-project}"
+```
+
+**Runtime support:**
+
+| Runtime | `${input:...}` support |
+|---------|----------------------|
+| VS Code | ✅ Prompts user at runtime |
+| Copilot CLI | ❌ Use environment variables instead |
+| Codex | ❌ Use environment variables instead |
+
 ## Roadmap
 
 The following IDE integrations are planned for future releases:

docs/src/content/docs/reference/manifest-schema.md

@@ -280,12 +280,12 @@ A plain registry reference: `io.github.github/github-mcp-server`
 |---|---|---|---|---|
 | `name` | `string` | REQUIRED | Non-empty | Server identifier (registry name or custom name). |
 | `transport` | `enum<string>` | Conditional | `stdio` · `sse` · `http` · `streamable-http` | Transport protocol. REQUIRED when `registry: false`. |
-| `env` | `map<string, string>` | OPTIONAL | | Environment variable overrides. |
+| `env` | `map<string, string>` | OPTIONAL | | Environment variable overrides. Values may contain `${input:<id>}` references (VS Code only — see §4.2.4). |
 | `args` | `dict` or `list` | OPTIONAL | | Dict for overlay variable overrides (registry), list for positional args (self-defined). |
 | `version` | `string` | OPTIONAL | | Pin to a specific server version. |
 | `registry` | `bool` or `string` | OPTIONAL | Default: `true` (public registry) | `false` = self-defined (private) server. String = custom registry URL. |
 | `package` | `enum<string>` | OPTIONAL | `npm` · `pypi` · `oci` | Package manager type hint. |
-| `headers` | `map<string, string>` | OPTIONAL | | Custom HTTP headers for remote endpoints. |
+| `headers` | `map<string, string>` | OPTIONAL | | Custom HTTP headers for remote endpoints. Values may contain `${input:<id>}` references (VS Code only — see §4.2.4). |
 | `tools` | `list<string>` | OPTIONAL | Default: `["*"]` | Restrict which tools are exposed. |
 | `url` | `string` | Conditional | | Endpoint URL. REQUIRED when `registry: false` and `transport` is `http`, `sse`, or `streamable-http`. |
 | `command` | `string` | Conditional | | Binary path. REQUIRED when `registry: false` and `transport` is `stdio`. |
@@ -320,6 +320,31 @@ dependencies:
         API_KEY: ${{ secrets.KEY }}
 ```
 
+#### 4.2.4. `${input:...}` Variables
+
+Values in `headers` and `env` may contain VS Code input variable references using the syntax `${input:<variable-id>}`. At runtime, VS Code prompts the user for each referenced input before starting the server.
+
+- **Registry-backed servers** — APM auto-generates input prompts from registry metadata.
+- **Self-defined servers** — APM detects `${input:...}` patterns in `apm.yml` and generates matching input definitions automatically.
+
+```yaml
+dependencies:
+  mcp:
+    - name: my-server
+      registry: false
+      transport: http
+      url: https://my-server.example.com/mcp/
+      headers:
+        Authorization: "Bearer ${input:my-server-token}"
+        X-Project: "${input:my-server-project}"
+```
+
+| Runtime | `${input:...}` support |
+|---------|----------------------|
+| VS Code | Yes — prompts user at runtime |
+| Copilot CLI | No — use environment variables |
+| Codex | No — use environment variables |
+
 ---
 
 ## 5. devDependencies