diff --git a/docs/src/content/docs/guides/mcps.md b/docs/src/content/docs/guides/mcps.md
index 8fadc5fcab..884b76553a 100644
--- a/docs/src/content/docs/guides/mcps.md
+++ b/docs/src/content/docs/guides/mcps.md
@@ -133,6 +133,22 @@ mcp-servers:
       - ask_question
 ```
 
+#### HTTP Authentication
+
+Configure authentication headers for HTTP MCP servers using the `headers` field:
+
+```yaml wrap
+mcp-servers:
+  authenticated-api:
+    url: "https://api.example.com/mcp"
+    headers:
+      Authorization: "Bearer ${{ secrets.API_TOKEN }}"
+      X-Custom-Header: "value"
+    allowed: ["*"]
+```
+
+Headers are injected into all HTTP requests made to the MCP server, enabling bearer token authentication, API keys, and other custom authentication schemes.
+
 ### 4. Registry-based MCP Servers
 
 Reference MCP servers from the GitHub MCP registry (the `registry` field provides metadata for tooling):
@@ -205,8 +221,6 @@ mcp-servers:
 
 Use `["*"]` to allow all tools from a custom MCP server.
 
-**HTTP Headers**: Configure authentication in URL parameters (e.g., `?apiKey=${{ secrets.API_KEY }}`).
-
 ## Network Egress Permissions
 
 Restrict outbound access for containerized stdio MCP servers using `network.allowed` (see [Docker Container example](#2-docker-container-mcp-servers)). Enforcement uses a [Squid proxy](https://www.squid-cache.org/) with `HTTP_PROXY`/`HTTPS_PROXY` and iptables rules. Only applies to containerized stdio servers.
diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md
index 365488246b..30438d3504 100644
--- a/docs/src/content/docs/reference/frontmatter.md
+++ b/docs/src/content/docs/reference/frontmatter.md
@@ -64,6 +64,24 @@ labels: ["automation", "ci", "diagnostics"]
 
 Labels help organize workflows by purpose, team, or functionality. They appear in status command table output as `[automation ci diagnostics]` and as a JSON array in `--json` mode. Filter workflows by label using `gh aw status --label automation`.
 
+### Metadata (`metadata:`)
+
+Optional key-value pairs for storing custom metadata compatible with the [GitHub Copilot custom agent spec](https://docs.github.com/en/copilot/reference/custom-agents-configuration).
+
+```yaml wrap
+metadata:
+  author: John Doe
+  version: 1.0.0
+  category: automation
+```
+
+**Constraints:**
+- Keys: 1-64 characters
+- Values: Maximum 1024 characters
+- Only string values are supported
+
+Metadata provides a flexible way to add descriptive information to workflows without affecting execution.
+
 ### GitHub Token (`github-token:`)
 
 Configures the default GitHub token for engine authentication, checkout steps, and safe-output operations.