diff --git a/.github/workflows/copilot.generate-tests.yml b/.github/workflows/copilot.generate-tests.yml
index 5b31fec..b2a7dc0 100644
--- a/.github/workflows/copilot.generate-tests.yml
+++ b/.github/workflows/copilot.generate-tests.yml
@@ -34,7 +34,8 @@ jobs:
                     
       - name: Analyze and generate tests with Copilot
         env:
-          GH_TOKEN: ${{ secrets.COPILOT_CLI_TOKEN }}
+          GH_TOKEN: ${{ secrets.COPILOT_CLI_TOKEN }}           # Personal PAT for Copilot API authentication
+          GITHUB_MCP_TOKEN: ${{ secrets.GITHUB_TOKEN }}        # Workflow token for MCP GitHub operations (issues)
         run: |
           echo "Analyzing commit ${{ github.sha }} for test coverage..."
           echo "Source files changed: ${{ steps.changes.outputs.source_count }}"
@@ -46,10 +47,12 @@ jobs:
           PROMPT="${PROMPT//\{REPOSITORY\}/${{ github.repository }}}"
           
           echo "Delegating to GitHub Copilot for test analysis..."
-          echo "- Copilot will examine the commit diff"
+          echo "- Copilot will use MCP to examine the commit diff"
           echo "- Copilot will check for corresponding test files"
           echo "- Copilot will assess if new tests are needed"
-          echo "- Copilot will create an issue if tests are recommended"
+          echo "- Copilot will create an issue and assign it to itself if needed"
           echo ""
 
-          copilot -p "$PROMPT" --enable-all-github-mcp-tools --allow-all-tools --no-ask-user
+          copilot -p "$PROMPT" \
+            --mcp-config .github/mcp.json \
+            --allow-all-tools
diff --git a/docs/development.md b/docs/development.md
index a8050fd..395ebef 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -421,6 +421,154 @@ az billing invoice list --output table
 
 ---
 
+## 🤖 Agentic Workflows with MCP
+
+### What is MCP?
+
+The **Model Context Protocol (MCP)** is a standard protocol that enables AI models like GitHub Copilot to interact with external tools and services. This repository leverages MCP to create autonomous workflows that can manage documentation, tests, and other development tasks.
+
+### MCP in This Repository
+
+This project includes MCP-enabled workflows that autonomously:
+
+- 📖 **Analyze code changes** - Examine commits for documentation or test needs
+- ✍️ **Create GitHub issues** - Automatically track required work
+- 👤 **Assign tasks** - Delegate to Copilot Coding Agent or team members
+- 🏷️ **Manage workflow** - Label, track, and close issues automatically
+
+### Available Agentic Workflows
+
+#### 1. Generate Documentation (`copilot.generate-docs.yml`)
+
+**What it does:**
+- Monitors code changes for documentation needs
+- Analyzes commit diffs using MCP GitHub integration
+- Creates issues when public APIs or complex logic is added
+- Assigns documentation tasks to Copilot
+
+**When it runs:**
+- Every push to the repository
+- Excludes changes to docs and markdown files
+
+**Learn more:** [labs/agentic-ci-workflows/copilot.generate-docs.md](../labs/agentic-ci-workflows/copilot.generate-docs.md)
+
+#### 2. Generate Tests (`copilot.generate-tests.yml`)
+
+**What it does:**
+- Identifies code lacking test coverage
+- Creates issues for missing or incomplete tests
+- Assigns test implementation to Copilot
+
+**When it runs:**
+- On push to main and pull requests
+- Excludes non-code changes
+
+**Learn more:** [labs/agentic-ci-workflows/copilot.generate-tests.md](../labs/agentic-ci-workflows/copilot.generate-tests.md)
+
+### Local MCP Setup
+
+To use MCP-enabled tools locally with Copilot CLI:
+
+#### Prerequisites
+
+```bash
+# Install GitHub CLI with Copilot extension
+gh auth login
+gh extension install github/gh-copilot
+
+# Or install standalone Copilot CLI
+curl -fsSL https://gh.io/copilot-install | bash
+```
+
+#### Configuration
+
+The MCP configuration file is already included in the repository:
+
+```bash
+# View the configuration
+cat .github/mcp.json
+```
+
+#### Usage Example
+
+```bash
+# Set up authentication tokens
+export GH_TOKEN="your_personal_access_token"  # Token with 'copilot' scope
+export GITHUB_MCP_TOKEN="$GH_TOKEN"           # Use same token locally
+
+# Run Copilot with MCP
+copilot -p "Analyze the latest commit for documentation needs" \
+  --mcp-config .github/mcp.json \
+  --allow-all-tools
+```
+
+**Flags explained:**
+- `--mcp-config .github/mcp.json` - Path to MCP configuration file (replaces deprecated `--enable-all-github-mcp-tools`)
+- `--allow-all-tools` - Allow Copilot to use all available MCP tools
+
+**Note:** The `--enable-all-github-mcp-tools` flag is deprecated. Always use `--mcp-config` with a configuration file instead.
+
+#### What You Can Do with MCP Locally
+
+- **Analyze code changes:** Ask Copilot to review commits and suggest improvements
+- **Generate documentation:** Request docs for specific functions or modules
+- **Create issues:** Have Copilot create GitHub issues for follow-up work
+- **Query repository:** Ask questions about codebase structure and history
+
+#### Example Prompts
+
+```bash
+# Analyze a specific commit
+copilot -p "Analyze commit abc1234 and determine if documentation is needed" \
+  --mcp-config .github/mcp.json --allow-all-tools
+
+# Generate documentation for a file
+copilot -p "Review src/app.ts and create API documentation" \
+  --mcp-config .github/mcp.json --allow-all-tools
+
+# Check test coverage
+copilot -p "Identify functions in src/utils.ts that lack unit tests" \
+  --mcp-config .github/mcp.json --allow-all-tools
+```
+
+### MCP Token Requirements
+
+When using MCP locally or in CI/CD:
+
+| Environment | Token Source | Required Scopes |
+|------------|--------------|-----------------|
+| **Local development** | Personal Access Token | `copilot`, `repo` |
+| **GitHub Actions** | `COPILOT_CLI_TOKEN` secret + `GITHUB_TOKEN` | `copilot` (PAT), `contents: read`, `issues: write` (workflow) |
+
+### Troubleshooting MCP Locally
+
+**Problem:** `Error: MCP authentication failed`
+
+**Solutions:**
+1. Check token is set: `echo $GH_TOKEN`
+2. Verify token has correct scopes (Settings → Developer settings → PAT)
+3. Ensure `.github/mcp.json` exists and is valid JSON
+
+**Problem:** `Cannot find mcp.json`
+
+**Solutions:**
+1. Verify file path: `ls .github/mcp.json`
+2. Use absolute path: `--mcp-config /full/path/to/.github/mcp.json`
+
+**Problem:** `Permission denied when creating issues`
+
+**Solutions:**
+1. Ensure token has `repo` scope (not just `copilot`)
+2. Verify you have write access to the repository
+
+### Learn More
+
+- **MCP Configuration Details:** [github-deployment.md - MCP Configuration](github-deployment.md#mcp-model-context-protocol-configuration)
+- **Workflow Setup:** [labs/agentic-ci-workflows/](../labs/agentic-ci-workflows/)
+- **Copilot CLI Docs:** [GitHub Copilot CLI Documentation](https://docs.github.com/en/copilot/github-copilot-in-the-cli)
+
+---
+
 **Last Updated:** December 2024
 
 **Version:** 1.0.0
diff --git a/docs/github-deployment.md b/docs/github-deployment.md
index f3009af..febb259 100644
--- a/docs/github-deployment.md
+++ b/docs/github-deployment.md
@@ -12,6 +12,7 @@ Automate your entire deployment pipeline with GitHub Actions. This guide covers
 - [Workflow Overview](#workflow-overview)
 - [Environments Explained](#environments-explained)
 - [Best Practices](#best-practices)
+- [MCP (Model Context Protocol) Configuration](#mcp-model-context-protocol-configuration)
 - [Troubleshooting](#troubleshooting)
 - [Security](#security)
 
@@ -248,6 +249,34 @@ az role assignment create \
 
 **That's the only secret needed!** Much simpler than before.
 
+---
+
+### Additional Secrets for Agentic Workflows (Optional)
+
+If you're using the agentic CI workflows (e.g., `copilot.generate-docs.yml`), you'll need this additional secret:
+
+| Name | Value | Source |
+|------|-------|--------|
+| `COPILOT_CLI_TOKEN` | Personal Access Token with Copilot scope | Create at https://github.com/settings/tokens |
+
+**Required token scopes:**
+- `copilot` - Access to GitHub Copilot API
+
+**How to create the token:**
+1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
+2. Click "Generate new token"
+3. Name: `Copilot CLI Token`
+4. Expiration: 90 days (recommended)
+5. Repository access: Select repositories that need Copilot workflows
+6. Permissions:
+   - Repository permissions → Copilot → Read and write
+7. Generate token and save it securely
+8. Add to repository secrets as `COPILOT_CLI_TOKEN`
+
+**Note:** The agentic workflows also use `GITHUB_TOKEN` (automatically provided by GitHub Actions) for MCP operations like creating issues. See the [MCP Configuration](#mcp-model-context-protocol-configuration) section below for details.
+
+---
+
 ### Configure Environments
 
 **Location:** Settings → Environments
@@ -634,6 +663,137 @@ Keep environments similar:
    - Availability tests failing
 3. Configure email/SMS notifications
 
+---
+
+## MCP (Model Context Protocol) Configuration
+
+### What is MCP?
+
+The **Model Context Protocol (MCP)** is a standard protocol that enables AI models like GitHub Copilot to interact with external tools and services. This repository uses MCP to power agentic workflows that can autonomously manage documentation and tests.
+
+### Why Use MCP?
+
+MCP enables GitHub Copilot to:
+
+- 📖 **Read repository content** - Examine code, diffs, and documentation
+- 🔍 **Navigate project structure** - Understand codebase organization
+- ✍️ **Create GitHub issues** - Automatically track work items
+- 👤 **Assign tasks** - Delegate work to humans or other agents
+- 🏷️ **Manage labels** - Organize and categorize issues
+- 🔄 **Interact with CI/CD** - Trigger and respond to workflow events
+
+### MCP Configuration File
+
+**Location:** `.github/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "type": "http",
+      "url": "https://api.githubcopilot.com/mcp/",
+      "headers": {
+        "Authorization": "Bearer ${GITHUB_MCP_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+#### Configuration Fields
+
+| Field | Value | Description |
+|-------|-------|-------------|
+| `mcpServers.github.type` | `http` | MCP server type (HTTP-based API) |
+| `mcpServers.github.url` | `https://api.githubcopilot.com/mcp/` | GitHub Copilot MCP server endpoint |
+| `mcpServers.github.headers.Authorization` | `Bearer ${GITHUB_MCP_TOKEN}` | Authentication using workflow token |
+
+The `${GITHUB_MCP_TOKEN}` environment variable is automatically substituted at runtime with the workflow's `GITHUB_TOKEN`.
+
+### Dual-Token Authentication Pattern
+
+Agentic workflows use **two different tokens** for different purposes:
+
+#### 1. `GH_TOKEN` (Copilot CLI Authentication)
+
+```yaml
+env:
+  GH_TOKEN: ${{ secrets.COPILOT_CLI_TOKEN }}
+```
+
+- **Purpose:** Authenticate Copilot CLI with GitHub Copilot API
+- **Source:** Repository secret `COPILOT_CLI_TOKEN`
+- **Used by:** Copilot CLI binary for API requests
+- **Required scope:** `copilot` (access to GitHub Copilot API)
+
+#### 2. `GITHUB_MCP_TOKEN` (MCP GitHub Operations)
+
+```yaml
+env:
+  GITHUB_MCP_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+- **Purpose:** Authenticate MCP server for GitHub operations
+- **Source:** Automatic workflow token (no secret needed)
+- **Used by:** MCP server (via `mcp.json` configuration)
+- **Required permissions:** Set in workflow `permissions:` block
+  - `contents: read` - Read repository files and commit diffs
+  - `issues: write` - Create and manage GitHub issues
+
+### Workflow Configuration Example
+
+```yaml
+name: Generate Documentation with Copilot
+
+on:
+  push:
+    paths-ignore:
+      - 'docs/**'
+      - '**.md'
+
+jobs:
+  generate-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read    # Required for MCP to read repository content
+      issues: write     # Required for MCP to create GitHub issues
+    
+    steps:
+      - name: Analyze and delegate to Copilot
+        env:
+          GH_TOKEN: ${{ secrets.COPILOT_CLI_TOKEN }}           # Copilot API auth
+          GITHUB_MCP_TOKEN: ${{ secrets.GITHUB_TOKEN }}        # MCP GitHub ops
+        run: |
+          copilot -p "$PROMPT" \
+            --mcp-config .github/mcp.json \
+            --allow-all-tools
+```
+
+### Token Scopes Summary
+
+| Token | Environment Variable | Source | Scopes/Permissions |
+|-------|---------------------|--------|-------------------|
+| Copilot CLI Token | `GH_TOKEN` | `secrets.COPILOT_CLI_TOKEN` | `copilot` scope |
+| MCP Token | `GITHUB_MCP_TOKEN` | `secrets.GITHUB_TOKEN` | `contents: read`, `issues: write` |
+
+### MCP-Enabled Workflows
+
+This repository includes the following MCP-enabled workflows:
+
+1. **Generate Documentation** (`.github/workflows/copilot.generate-docs.yml`)
+   - Analyzes commits for documentation needs
+   - Creates issues for missing or outdated docs
+   - Assigns documentation tasks to Copilot
+
+2. **Generate Tests** (`.github/workflows/copilot.generate-tests.yml`)
+   - Identifies code missing test coverage
+   - Creates issues for test implementation
+   - Delegates test writing to Copilot
+
+For detailed workflow documentation, see [`labs/agentic-ci-workflows/`](../labs/agentic-ci-workflows/).
+
+---
+
 ### 6. Security
 
 - ✅ Use service principals (not personal access tokens)
@@ -787,6 +947,107 @@ az staticwebapp secrets list \
 4. Approve for "production"
 5. Workflow continues
 
+### MCP Workflows Failing
+
+#### Problem: `Error: MCP authentication failed` or `401 Unauthorized`
+
+**Solutions:**
+
+1. **Verify workflow permissions:**
+   ```yaml
+   permissions:
+     contents: read    # Required to read repository content
+     issues: write     # Required to create GitHub issues
+   ```
+
+2. **Check MCP token configuration:**
+   - Ensure `GITHUB_MCP_TOKEN` is set to `${{ secrets.GITHUB_TOKEN }}`
+   - Verify token is passed as environment variable to the step
+
+3. **Validate MCP configuration file:**
+   ```bash
+   # Check file exists
+   cat .github/mcp.json
+   
+   # Validate JSON syntax
+   jq . .github/mcp.json
+   ```
+
+4. **Verify Copilot CLI token:**
+   - Ensure `COPILOT_CLI_TOKEN` secret exists
+   - Check token hasn't expired (90-day default)
+   - Verify token has `copilot` scope
+
+#### Problem: `Error: Cannot find mcp.json` or `Invalid MCP configuration`
+
+**Solutions:**
+
+1. **Verify file path:**
+   ```bash
+   # File must exist at repository root
+   ls -la .github/mcp.json
+   ```
+
+2. **Check JSON syntax:**
+   - No trailing commas
+   - Proper quote escaping
+   - Valid JSON structure
+
+3. **Ensure correct flag usage:**
+   ```yaml
+   # Correct (current)
+   copilot -p "$PROMPT" \
+     --mcp-config .github/mcp.json \
+     --allow-all-tools
+   
+   # Incorrect (deprecated)
+   copilot -p "$PROMPT" --enable-all-github-mcp-tools
+   ```
+
+#### Problem: `Copilot created issue but couldn't read commit diff`
+
+**Solutions:**
+
+1. **Check permissions:**
+   - Verify `contents: read` is granted in workflow
+   - Ensure repository is accessible to workflow token
+
+2. **Validate commit reference:**
+   ```bash
+   # Check commit exists
+   git show ${{ github.sha }}
+   
+   # Verify commit is in current branch
+   git log --oneline | grep ${{ github.sha }}
+   ```
+
+3. **Review workflow logs:**
+   - Look for MCP server connection errors
+   - Check for rate limiting issues
+   - Verify API endpoint is accessible
+
+#### Problem: `COPILOT_CLI_TOKEN` not working
+
+**Solutions:**
+
+1. **Recreate the token:**
+   - Go to GitHub Settings → Developer settings → Personal access tokens
+   - Generate new fine-grained token
+   - Select repository access
+   - Grant `copilot` scope (Read and write)
+   - Update `COPILOT_CLI_TOKEN` secret
+
+2. **Verify token format:**
+   ```bash
+   # Token should start with github_pat_
+   echo $GH_TOKEN | head -c 20
+   ```
+
+3. **Check token expiration:**
+   - Tokens expire after 90 days by default
+   - Set up calendar reminder to rotate tokens
+   - Consider using longer expiration for CI/CD
+
 ---
 
 ## Security
diff --git a/labs/agentic-ci-workflows/copilot.generate-docs.md b/labs/agentic-ci-workflows/copilot.generate-docs.md
index bb19374..59bc532 100644
--- a/labs/agentic-ci-workflows/copilot.generate-docs.md
+++ b/labs/agentic-ci-workflows/copilot.generate-docs.md
@@ -71,11 +71,86 @@ on:
       - '.github/workflows/**'
 ```
 
-### Required Secrets
+### Required Secrets & Tokens
 
-| Secret | Description |
-|--------|-------------|
-| `COPILOT_CLI_TOKEN` | Personal Access Token with Copilot permissions |
+The workflow uses a **dual-token authentication pattern** for different purposes:
+
+| Token/Secret | Environment Variable | Description | Permissions Required |
+|--------------|---------------------|-------------|---------------------|
+| `COPILOT_CLI_TOKEN` | `GH_TOKEN` | Personal Access Token for Copilot CLI authentication | `copilot` scope |
+| `GITHUB_TOKEN` (automatic) | `GITHUB_MCP_TOKEN` | Workflow token for MCP GitHub operations | `contents: read`, `issues: write` |
+
+#### Token Usage Breakdown
+
+**`GH_TOKEN` (Copilot CLI Token)**
+- Used by: Copilot CLI for API authentication
+- Authenticates: Requests to GitHub Copilot API
+- Source: Repository secret (`COPILOT_CLI_TOKEN`)
+- Required scope: `copilot` (GitHub Copilot API access)
+
+**`GITHUB_MCP_TOKEN` (MCP Operations Token)**
+- Used by: MCP server for GitHub operations (via `mcp.json`)
+- Authenticates: GitHub API calls (create issues, list repos, read files)
+- Source: Automatic workflow token (`secrets.GITHUB_TOKEN`)
+- Required permissions: Set in workflow `permissions:` block
+  - `contents: read` - Read repository content and commit diffs
+  - `issues: write` - Create and manage GitHub issues
+
+---
+
+## MCP (Model Context Protocol) Configuration
+
+### What is MCP?
+
+The **Model Context Protocol (MCP)** is a standard protocol that allows AI models like GitHub Copilot to interact with external tools and services. In this workflow, MCP enables Copilot to:
+
+- 📖 Read repository files and commit diffs
+- 🔍 Navigate project structure
+- ✍️ Create GitHub issues
+- 👤 Assign issues to users (including itself)
+- 🏷️ Add labels to issues
+
+### MCP Configuration File
+
+**Location**: [`.github/mcp.json`](../../.github/mcp.json)
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "type": "http",
+      "url": "https://api.githubcopilot.com/mcp/",
+      "headers": {
+        "Authorization": "Bearer ${GITHUB_MCP_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+#### Configuration Fields
+
+| Field | Value | Description |
+|-------|-------|-------------|
+| `mcpServers.github.type` | `http` | MCP server type (HTTP-based API) |
+| `mcpServers.github.url` | `https://api.githubcopilot.com/mcp/` | GitHub Copilot MCP server endpoint |
+| `mcpServers.github.headers.Authorization` | `Bearer ${GITHUB_MCP_TOKEN}` | Authentication header with workflow token |
+
+The `${GITHUB_MCP_TOKEN}` environment variable is automatically substituted by the Copilot CLI at runtime.
+
+### Workflow Configuration
+
+The workflow passes the MCP configuration to Copilot CLI:
+
+```yaml
+copilot -p "$PROMPT" \
+  --mcp-config .github/mcp.json \
+  --allow-all-tools
+```
+
+**Flags explained:**
+- `--mcp-config .github/mcp.json` - Path to MCP configuration file (replaces deprecated `--enable-all-github-mcp-tools`)
+- `--allow-all-tools` - Allow Copilot to use all available MCP tools
 
 ---
 
@@ -132,7 +207,57 @@ When the workflow detects documentation is needed, it creates an issue like:
 - Verify the token has `Copilot Requests` permission
 - Check workflow logs for authentication errors
 
+### MCP Authentication Failures
+
+**Problem**: `Error: MCP authentication failed` or `401 Unauthorized`
+
+**Solutions**:
+1. Verify workflow has correct permissions:
+   ```yaml
+   permissions:
+     contents: read    # Required to read repository content
+     issues: write     # Required to create GitHub issues
+   ```
+2. Check that `GITHUB_MCP_TOKEN` is set to `${{ secrets.GITHUB_TOKEN }}`
+3. Ensure `.github/mcp.json` exists and has correct format
+4. Verify MCP server URL is accessible: `https://api.githubcopilot.com/mcp/`
+
+**Problem**: `Error: Cannot find mcp.json` or `Invalid MCP configuration`
+
+**Solutions**:
+1. Verify `.github/mcp.json` exists in repository root
+2. Validate JSON syntax (no trailing commas, proper quotes)
+3. Check file is not in `.gitignore`
+4. Ensure `--mcp-config` path is correct: `--mcp-config .github/mcp.json`
+
+**Problem**: `Copilot created issue but couldn't read commit diff`
+
+**Solutions**:
+1. Verify `contents: read` permission is granted
+2. Check that commit SHA is valid and exists in repository
+3. Ensure MCP token has access to private repositories (if applicable)
+
 ### Agent Not Implementing Documentation
 
 - Confirm Copilot Coding Agent is enabled in repository settings
 - Verify the issue is properly assigned to `@copilot`
+
+---
+
+## Migration from Deprecated Flag
+
+If you're upgrading from an older version of this workflow, note the following change:
+
+**Before** (deprecated):
+```yaml
+copilot -p "$PROMPT" --enable-all-github-mcp-tools
+```
+
+**After** (current):
+```yaml
+copilot -p "$PROMPT" \
+  --mcp-config .github/mcp.json \
+  --allow-all-tools
+```
+
+The `--enable-all-github-mcp-tools` flag is deprecated. Use `--mcp-config` with a configuration file instead.
diff --git a/labs/agentic-ci-workflows/copilot.generate-tests.md b/labs/agentic-ci-workflows/copilot.generate-tests.md
index a1f7f45..57b6a41 100644
--- a/labs/agentic-ci-workflows/copilot.generate-tests.md
+++ b/labs/agentic-ci-workflows/copilot.generate-tests.md
@@ -79,13 +79,88 @@ on:
       - '**/*.d.ts'
 ```
 
-### Required Secrets
+### Required Secrets & Tokens
 
-| Secret | Description |
-|--------|-------------|
-| `COPILOT_CLI_TOKEN` | Personal Access Token with Copilot permissions |
+The workflow uses a **dual-token authentication pattern** for different purposes:
 
+| Token/Secret | Environment Variable | Description | Permissions Required |
+|--------------|---------------------|-------------|---------------------|
+| `COPILOT_CLI_TOKEN` | `GH_TOKEN` | Personal Access Token for Copilot CLI authentication | `copilot` scope |
+| `GITHUB_TOKEN` (automatic) | `GITHUB_MCP_TOKEN` | Workflow token for MCP GitHub operations | `contents: read`, `issues: write` |
 
+#### Token Usage Breakdown
+
+**`GH_TOKEN` (Copilot CLI Token)**
+- Used by: Copilot CLI for API authentication
+- Authenticates: Requests to GitHub Copilot API
+- Source: Repository secret (`COPILOT_CLI_TOKEN`)
+- Required scope: `copilot` (GitHub Copilot API access)
+
+**`GITHUB_MCP_TOKEN` (MCP Operations Token)**
+- Used by: MCP server for GitHub operations (via `mcp.json`)
+- Authenticates: GitHub API calls (create issues, list repos, read files)
+- Source: Automatic workflow token (`secrets.GITHUB_TOKEN`)
+- Required permissions: Set in workflow `permissions:` block
+  - `contents: read` - Read repository content and commit diffs
+  - `issues: write` - Create and manage GitHub issues
+
+---
+
+## MCP (Model Context Protocol) Configuration
+
+### What is MCP?
+
+The **Model Context Protocol (MCP)** is a standard protocol that allows AI models like GitHub Copilot to interact with external tools and services. In this workflow, MCP enables Copilot to:
+
+- 📖 Read repository files and commit diffs
+- 🔍 Navigate project structure
+- ✍️ Create GitHub issues
+- 👤 Assign issues to users (including itself)
+- 🏷️ Add labels to issues
+
+### MCP Configuration File
+
+**Location**: [`.github/mcp.json`](../../.github/mcp.json)
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "type": "http",
+      "url": "https://api.githubcopilot.com/mcp/",
+      "headers": {
+        "Authorization": "Bearer ${GITHUB_MCP_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+#### Configuration Fields
+
+| Field | Value | Description |
+|-------|-------|-------------|
+| `mcpServers.github.type` | `http` | MCP server type (HTTP-based API) |
+| `mcpServers.github.url` | `https://api.githubcopilot.com/mcp/` | GitHub Copilot MCP server endpoint |
+| `mcpServers.github.headers.Authorization` | `Bearer ${GITHUB_MCP_TOKEN}` | Authentication header with workflow token |
+
+The `${GITHUB_MCP_TOKEN}` environment variable is automatically substituted by the Copilot CLI at runtime.
+
+### Workflow Configuration
+
+The workflow passes the MCP configuration to Copilot CLI:
+
+```yaml
+copilot -p "$PROMPT" \
+  --mcp-config .github/mcp.json \
+  --allow-all-tools
+```
+
+**Flags explained:**
+- `--mcp-config .github/mcp.json` - Path to MCP configuration file (replaces deprecated `--enable-all-github-mcp-tools`)
+- `--allow-all-tools` - Allow Copilot to use all available MCP tools
+
+---
 
 ## Prompt File
 
@@ -168,6 +243,42 @@ describe('Warehouse Routes', () => {
 - Ensure changes are not exclusively in `paths-ignore` patterns
 - Check that the workflow file exists in the default branch
 
+### Copilot Not Creating Issues
+
+- Ensure `COPILOT_CLI_TOKEN` secret is configured
+- Verify the token has `Copilot Requests` permission
+- Check workflow logs for authentication errors
+
+### MCP Authentication Failures
+
+**Problem**: `Error: MCP authentication failed` or `401 Unauthorized`
+
+**Solutions**:
+1. Verify workflow has correct permissions:
+   ```yaml
+   permissions:
+     contents: read    # Required to read repository content
+     issues: write     # Required to create GitHub issues
+   ```
+2. Check that `GITHUB_MCP_TOKEN` is set to `${{ secrets.GITHUB_TOKEN }}`
+3. Ensure `.github/mcp.json` exists and has correct format
+4. Verify MCP server URL is accessible: `https://api.githubcopilot.com/mcp/`
+
+**Problem**: `Error: Cannot find mcp.json` or `Invalid MCP configuration`
+
+**Solutions**:
+1. Verify `.github/mcp.json` exists in repository root
+2. Validate JSON syntax (no trailing commas, proper quotes)
+3. Check file is not in `.gitignore`
+4. Ensure `--mcp-config` path is correct: `--mcp-config .github/mcp.json`
+
+**Problem**: `Copilot created issue but couldn't read commit diff`
+
+**Solutions**:
+1. Verify `contents: read` permission is granted
+2. Check that commit SHA is valid and exists in repository
+3. Ensure MCP token has access to private repositories (if applicable)
+
 ### Copilot Not Detecting Missing Tests
 
 - Review the generate-tests prompt for coverage criteria
@@ -185,3 +296,23 @@ describe('Warehouse Routes', () => {
 - Run tests locally to identify issues
 - Check for missing imports or dependencies
 - Verify mock data matches the expected schema
+
+---
+
+## Migration from Deprecated Flag
+
+If you're upgrading from an older version of this workflow, note the following change:
+
+**Before** (deprecated):
+```yaml
+copilot -p "$PROMPT" --enable-all-github-mcp-tools
+```
+
+**After** (current):
+```yaml
+copilot -p "$PROMPT" \
+  --mcp-config .github/mcp.json \
+  --allow-all-tools
+```
+
+The `--enable-all-github-mcp-tools` flag is deprecated. Use `--mcp-config` with a configuration file instead.