diff --git a/.github/instructions/github-agentic-workflows.instructions.md b/.github/instructions/github-agentic-workflows.instructions.md
index a34fc67f67d..9d2d78c1c84 100644
--- a/.github/instructions/github-agentic-workflows.instructions.md
+++ b/.github/instructions/github-agentic-workflows.instructions.md
@@ -462,12 +462,12 @@ tools:
 ```
 
 ### Custom MCP Tools
+
 ```yaml
-tools:
+mcp-servers:
   my-custom-tool:
-    mcp:
-      command: "node"
-      args: ["path/to/mcp-server.js"]
+    command: "node"
+    args: ["path/to/mcp-server.js"]
     allowed:
       - custom_function_1
       - custom_function_2
diff --git a/docs/src/content/docs/guides/mcps.md b/docs/src/content/docs/guides/mcps.md
index 1fc456f758a..20b23efac3d 100644
--- a/docs/src/content/docs/guides/mcps.md
+++ b/docs/src/content/docs/guides/mcps.md
@@ -18,31 +18,68 @@ Model Context Protocol (MCP) is a standardized protocol that allows AI agents to
 
 ### Basic MCP Configuration
 
-Add MCP servers to your workflow's frontmatter:
+Add MCP servers to your workflow's frontmatter using the `mcp-servers:` section:
 
 ```yaml
 ---
-tools:
-  github:
-    allowed: [get_issue, add_issue_comment]
-  
+on: issues
+permissions:
+  contents: read
+  issues: write
+engine: claude
+mcp-servers:
   trello:
-    type: stdio
     command: "python"
     args: ["-m", "trello_mcp"]
     env:
       TRELLO_TOKEN: "${{ secrets.TRELLO_TOKEN }}"
-    allowed: ["list_boards"]
+    allowed: ["list_boards", "create_card"]
+  
+  notion:
+    registry: https://api.mcp.github.com/v0/servers/makenotion/notion-mcp-server
+    command: npx
+    args: ["-y", "@makenotion/notion-mcp-server"]
+    env:
+      NOTION_TOKEN: "${{ secrets.NOTION_TOKEN }}"
+    allowed: ["search_pages", "create_page"]
 ---
 
 # Your workflow content here
 ```
 
 > [!TIP]
-> You can inspect test your MCP configuration by running <br/>
+> You can inspect and test your MCP configuration by running <br/>
 > `gh aw mcp inspect <workflow-file>`
 
 
+### Adding MCP Servers from the Registry
+
+The easiest way to add MCP servers is using the GitHub MCP registry with the `gh aw mcp add` command:
+
+```bash
+# List available MCP servers from the registry
+gh aw mcp add
+
+# Add a specific MCP server to your workflow
+gh aw mcp add my-workflow makenotion/notion-mcp-server
+
+# Add with specific transport preference
+gh aw mcp add my-workflow makenotion/notion-mcp-server --transport stdio
+
+# Add with custom tool ID
+gh aw mcp add my-workflow makenotion/notion-mcp-server --tool-id my-notion
+
+# Use a custom registry
+gh aw mcp add my-workflow server-name --registry https://custom.registry.com/v1
+```
+
+This command automatically:
+- Searches the MCP registry for the specified server
+- Adds the server configuration to your workflow's `mcp-servers:` section (using the modern format)
+- Compiles the workflow to generate the `.lock.yml` file
+
+**Default Registry**: `https://api.mcp.github.com/v0`
+
 ### Engine Compatibility
 
 Different AI engines support different MCP features:
@@ -59,9 +96,8 @@ Different AI engines support different MCP features:
 Direct command execution with stdin/stdout communication:
 
 ```yaml
-tools:
+mcp-servers:
   python-service:
-    type: stdio
     command: "python"
     args: ["-m", "my_mcp_server"]
     env:
@@ -77,9 +113,8 @@ tools:
 Containerized MCP servers for isolation and portability:
 
 ```yaml
-tools:
+mcp-servers:
   notion:
-    type: stdio
     container: "mcp/notion"
     env:
       NOTION_TOKEN: "${{ secrets.NOTION_TOKEN }}"
@@ -97,9 +132,8 @@ The `container` field automatically generates:
 Remote MCP servers accessible via HTTP (Claude engine only):
 
 ```yaml
-tools:
+mcp-servers:
   remote-api:
-    type: http
     url: "https://api.example.com/mcp"
     headers:
       Authorization: "Bearer ${{ secrets.API_TOKEN }}"
@@ -109,6 +143,21 @@ tools:
 
 **Use cases**: Cloud services, remote APIs, shared infrastructure
 
+### 4. Registry-based MCP Servers
+
+MCP servers that reference entries in the GitHub MCP registry:
+
+```yaml
+mcp-servers:
+  markitdown:
+    registry: https://api.mcp.github.com/v0/servers/microsoft/markitdown
+    command: npx
+    args: ["-y", "@microsoft/markitdown"]
+    allowed: ["convert_html", "convert_pdf"]
+```
+
+**Registry Reference**: The `registry` field provides metadata about the MCP server's origin and can help with tooling and documentation.
+
 ## GitHub MCP Integration
 
 GitHub Agentic Workflows includes built-in GitHub MCP integration with comprehensive repository access. See [Tools Configuration](/gh-aw/reference/tools/) for details.
@@ -131,9 +180,8 @@ When using an agentic engine that allows tool whitelisting (e.g. Claude), you ca
 ### Specific Tools
 
 ```yaml
-tools:
+mcp-servers:
   custom-server:
-    type: stdio
     command: "python"
     args: ["-m", "my_server"]
     allowed: ["tool1", "tool2", "tool3"]
@@ -148,9 +196,8 @@ When using an agentic engine that allows tool whitelisting (e.g. Claude), this g
 ### Wildcard Access
 
 ```yaml
-tools:
+mcp-servers:
   custom-server:
-    type: stdio
     command: "python"
     args: ["-m", "my_server"]
     allowed: ["*"]  # Allow ALL tools from this server
@@ -160,10 +207,11 @@ When using an agentic engine that allows tool whitelisting (e.g. Claude), this g
 
 ### HTTP Headers
 
+HTTP headers can be configured for remote MCP servers:
+
 ```yaml
-tools:
+mcp-servers:
   remote-api:
-    type: http
     url: "https://api.service.com"
     headers:
       Authorization: "Bearer ${{ secrets.API_TOKEN }}"
@@ -175,9 +223,8 @@ tools:
 Restrict outbound network access for containerized MCP servers using a per‑tool domain allowlist. Define allowed domains under `permissions.network.allowed`.
 
 ```yaml
-tools:
+mcp-servers:
   fetch:
-    type: stdio
     container: mcp/fetch
     permissions:
       network:
@@ -201,8 +248,8 @@ Notes:
 
 The compiler enforces these network permission rules:
 
-- ❌ **HTTP servers**: `network egress permissions do not apply to remote 'type: http' servers`
-- ❌ **Non-container stdio**: `network egress permissions only apply to stdio MCP servers that specify a 'container'`  
+- ❌ **HTTP servers**: `network egress permissions do not apply to remote HTTP MCP servers`
+- ❌ **Non-container stdio**: `network egress permissions only apply to containerized MCP servers`  
 - ✅ **Container stdio**: Network permissions work correctly
 
 ## Debugging and Troubleshooting
diff --git a/docs/src/content/docs/reference/tools.md b/docs/src/content/docs/reference/tools.md
index f099e7d911b..ebba4d44314 100644
--- a/docs/src/content/docs/reference/tools.md
+++ b/docs/src/content/docs/reference/tools.md
@@ -105,25 +105,46 @@ tools:
 **Available Ecosystem Identifiers:**
 Same as `network:` configuration: `defaults`, `github`, `node`, `python`, `containers`, `java`, `rust`, `playwright`, etc.
 
-## Custom MCP Tools
+## MCP Server Integration
 
-Add custom Model Context Protocol servers for specialized integrations:
+Use the dedicated `mcp-servers:` section for MCP server configuration:
 
 ```yaml
-tools:
+# In your workflow frontmatter
+mcp-servers:
   custom-api:
-    mcp:
-      command: "node"
-      args: ["custom-mcp-server.js"]
-      env:
-        API_KEY: "${{ secrets.CUSTOM_API_KEY }}"
+    command: "node"
+    args: ["custom-mcp-server.js"]
+    env:
+      API_KEY: "${{ secrets.CUSTOM_API_KEY }}"
+
+# Separate tools section for built-in capabilities
+tools:
+  github:
+    allowed: [create_issue, update_issue]
+  playwright:
+    allowed_domains: ["github.com"]
 ```
 
-**Tool Execution:**
-- Tools are configured as MCP servers that run alongside the AI engine
-- Each tool provides specific capabilities (APIs, browser automation, etc.)
-- Tools run in isolated environments with controlled access
-- Domain restrictions apply to network-enabled tools like Playwright
+### Adding MCP Servers from Registry
+
+The easiest way to add MCP servers is from the GitHub MCP registry:
+
+```bash
+# List available MCP servers
+gh aw mcp add
+
+# Add a specific server to your workflow  
+gh aw mcp add my-workflow makenotion/notion-mcp-server
+```
+
+See the [MCP Integration Guide](/gh-aw/guides/mcps/) for comprehensive MCP server setup and configuration.
+
+**MCP Server Execution:**
+- MCP servers run alongside the AI engine to provide specialized capabilities
+- Each server provides specific tools (APIs, database access, etc.)
+- Servers run in isolated environments with controlled access
+- Domain restrictions apply to network-enabled servers
 
 ## Neutral Tools (`edit:`, `web-fetch:`, `web-search:`, `bash:`)
 
diff --git a/docs/src/content/docs/tools/cli.md b/docs/src/content/docs/tools/cli.md
index 2987deabd89..be7138e0dec 100644
--- a/docs/src/content/docs/tools/cli.md
+++ b/docs/src/content/docs/tools/cli.md
@@ -305,8 +305,12 @@ gh aw mcp inspect workflow-name --inspector
 
 ### MCP Server Management
 
+The MCP commands help you discover, add, and manage MCP servers from the GitHub MCP registry.
+
+#### Adding MCP Servers from Registry
+
 ```bash
-# List available MCP servers from the registry
+# List available MCP servers from the GitHub MCP registry
 gh aw mcp add
 
 # Add an MCP server to a workflow from the registry
@@ -320,7 +324,18 @@ gh aw mcp add weekly-research makenotion/notion-mcp-server --tool-id my-notion
 
 # Use custom MCP registry
 gh aw mcp add weekly-research server-name --registry https://custom.registry.com/v1
+```
 
+**Key Features:**
+- **Automatic Configuration**: Uses the modern `mcp-servers:` format in your workflow frontmatter
+- **Registry Integration**: Connects to GitHub's MCP registry at `https://api.mcp.github.com/v0` by default
+- **Automatic Compilation**: Compiles the workflow after adding the MCP server
+- **Transport Selection**: Supports stdio, HTTP, and Docker transports
+- **Custom Registries**: Can connect to private or custom MCP registries
+
+#### MCP Server Development
+
+```bash
 # Launch MCP server exposing gh-aw CLI tools
 gh aw mcp serve