Skip to content

MCP-Assisted Migration to Forge v3

Forge v3 introduces an AI-powered migration assistant via the SAIF MCP (Model Context Protocol) server that automates the migration process from Forge v2 to v3.

The challenge: Manual migration involves dozens of file edits across .NET projects, Terraform modules, and pipeline configurations—time-consuming and error-prone.

The solution: The SAIF MCP server provides Copilot with migration knowledge, automated file discovery, and step-by-step execution guidance, reducing migration time from hours to minutes.

On this page

📋 Overview

Aspect Details
Goal Migrate a Forge v2 application to v3 using AI-assisted automation via the SAIF MCP server
Prerequisites VS Code with Copilot, .NET 10 SDK, SAIF CLI 3.0+, Aspire 13.1+
Time estimate ~30-45 minutes (vs 2-4 hours manual)
Difficulty Intermediate (requires understanding of git, pipelines, and basic troubleshooting)

🔧 Prerequisites

Before starting, ensure you have:

  • ✅ VS Code installed with the GitHub Copilot extension
  • ✅ .NET 10 SDK — Download from dotnet.microsoft.com/download/dotnet/10.0
  • ✅ SAIF CLI 3.0+ — Verify with saif --version
  • ✅ Aspire 13.1+ — Verify with aspire --version
  • ✅ Repository access — Clone permissions for your application repository
  • ✅ Azure DevOps access — Permissions to create/delete pipelines

💡 Tip: If your SAIF CLI or Aspire versions are outdated, run saif update twice with a 20-second pause between runs to ensure all updates complete.

🚀 Instructions

Signposting: This guide walks through (1) updating prerequisites, (2) initializing the MCP server, (3) running the AI-assisted migration, and (4) cleaning up old pipelines.

Step 1: Update Prerequisites

Before starting the migration, ensure all tools are up to date.

# Verify current versions
dotnet --version  # Should be 10.0.x
saif --version    # Should be 3.0.x
aspire --version  # Should be 13.1.x

# If outdated, update SAIF CLI and Aspire
saif update
Start-Sleep -Seconds 20
saif update
Start-Sleep -Seconds 20

# Verify updates
saif --version
aspire --version

Expected result: All version checks pass with minimum required versions.

⚠️ Important: Close all open terminals and VS Code instances after updating to ensure the new Aspire CLI path is loaded.

Step 2: Initialize MCP Server

The MCP server connects GitHub Copilot to the Forge platform documentation and migration tools.

  1. Close all VS Code windows and terminals to pick up the updated Aspire path
  2. Open VS Code in your application repository root
  3. Open a new terminal in VS Code (Ctrl+ `)
  4. Initialize MCP configuration:
saif mcp init

Expected result: A .vscode/mcp.json configuration file is created in your repository.

💡 Tip: The mcp.json file is ignored by git (in .gitignore) and specific to your local environment.

Step 3: Run AI-Assisted Migration

Now you'll use Copilot's agent chat to execute the migration.

  1. Open Copilot Agent Chat in VS Code:
  2. Click the Copilot icon in the sidebar

  3. Switch to the Agent Chat tab (not inline chat)

  4. Select the agent model:

  5. Choose Claude Opus or Claude Sonnet for best results

  6. Opus has stronger reasoning for complex migrations; Sonnet is faster

  7. Invoke the migration prompt:

/mcp.forge.migrate-to-v3

What happens next:

  • Copilot retrieves the Forge v2 to v3 Migration Guide
  • Creates a local copy in docs/migration/forge-v2-to-v3.md for progress tracking
  • Establishes a todo list with 10 migration tasks
  • Systematically executes each task:
  • Discovers files that need updates
  • Applies changes using multi-file edit operations
  • Runs dotnet build after each section
  • Updates progress checkboxes in the local migration doc
  • Marks todos complete before moving to the next task

💡 Tip: The agent will use #runSubagent to parallelize file discovery tasks, significantly speeding up the migration.

Expected result: Copilot progressively completes all 10 migration tasks, providing status updates after each section.

Step 4: Review and Test Migration

After Copilot completes the migration, verify the changes.

  1. Review the changes in git:
git status
git diff
  1. Build the project:
dotnet clean
dotnet restore
dotnet build
  1. Run tests:
dotnet test
  1. Start the AppHost locally:
cd src/{YourApp}.AppHost
aspire run

Expected result: All builds succeed, tests pass, and the Aspire dashboard loads successfully.

Step 5: Update Azure DevOps Pipelines

The final step is cleaning up old Okta-specific pipelines and creating the new unified auth pipelines.

⚠️ Important: Complete these steps in the Azure DevOps portal—they cannot be automated via the MCP server.

Delete Legacy Pipelines

Navigate to Pipelines in your Azure DevOps project and delete these pipelines:

  • {project-id}-okta-appauth-pr
  • {project-id}-okta-appauth
  • {project-id}-okta-userauth-pr
  • {project-id}-okta-userauth

How to delete:

  1. Go to the pipeline in Azure DevOps
  2. Click the ⋯ (More actions) menu
  3. Select Delete
  4. Confirm deletion

Create New Auth Pipelines

Create two new pipelines using the updated YAML files:

  1. {project-id}-auth-pr — PR validation for auth infrastructure
  2. Source: .azdo/azure-pipelines-auth-pr.yml

  3. Trigger: Pull requests affecting infra/auth/**

  4. {project-id}-auth — Production deployment for auth infrastructure

  5. Source: .azdo/azure-pipelines-auth.yml
  6. Trigger: Manual (same as existing pipelines)

How to create:

  1. In Azure DevOps, go to Pipelines → New pipeline
  2. Select Azure Repos Git
  3. Choose your repository
  4. Select Existing Azure Pipelines YAML file
  5. Browse to the YAML file path
  6. Click Continue → Save (not Run)
  7. Rename the pipeline to match the naming convention

Expected result: Four legacy Okta pipelines deleted, two new unified auth pipelines created.

✅ Verify It Worked

After completing all steps, verify the migration:

  1. Check version compatibility:
# All .csproj files should target net10.0
Select-String -Path "**/*.csproj" -Pattern "<TargetFramework>net10.0</TargetFramework>"
  1. Verify Aspire SDK:
# AppHost project should use Aspire.AppHost.Sdk/13.1.0
Get-Content "src/*AppHost/*.csproj" | Select-String "Aspire.AppHost.Sdk"

  1. Check folder structure:

  2. ✅ infra/api/ exists (renamed from infra/app/)

  3. ✅ infra/auth/corp/ exists (new for Entra ID)

  4. ✅ infra/auth/ext/ contains Okta configuration

  5. Confirm pipeline updates:

  6. ✅ .azdo/azure-pipelines-api.yml references azure-dotnet-api-v3.yml@templates

  7. ✅ Pipeline templates reference refs/heads/releases/v3
  8. ✅ New auth pipelines exist in Azure DevOps

Success indicator:

Build succeeded.
    0 Warning(s)
    0 Error(s)

🎯 Key Takeaways

After completing this guide, you will have:

  • ✅ Upgraded your application to .NET 10, Aspire 13, and Forge 3.0 packages
  • ✅ Restructured infrastructure to support dual authentication (Entra ID + Okta)
  • ✅ Updated pipelines to use v3 templates with refs/heads/releases/v3
  • ✅ Cleaned up legacy Okta-specific pipelines
  • ✅ Experienced AI-assisted migration with the SAIF MCP server

🔍 Troubleshooting

Problem: MCP server not found

Cause: SAIF CLI is outdated or MCP configuration wasn't initialized.

Solution:

# Update SAIF CLI
saif update
Start-Sleep -Seconds 20
saif update

# Reinitialize MCP
saif mcp init

# Restart VS Code

Problem: Copilot doesn't recognize /mcp.forge.migrate-to-v3

Cause: MCP server isn't running or the prompt isn't registered.

Solution:

  1. Verify mcp.json exists in .vscode/
  2. Restart VS Code to reload MCP configuration
  3. In Agent Chat, type / and verify mcp.forge.migrate-to-v3 appears in the suggestions
  4. If still missing, run saif mcp start manually and check for errors

Problem: Migration stops partway through

Cause: Copilot encountered an unexpected file structure or build error.

Solution:

  1. Check the Copilot chat for error messages
  2. Review the last completed todo item
  3. Manually complete the failed step using the manual migration guide
  4. Ask Copilot to resume from the next task: "Continue with the next migration task"

Problem: Build fails after migration

Cause: Package restore issue or stale build artifacts.

Solution:

# Clear NuGet cache and rebuild
dotnet nuget locals all --clear
dotnet clean
dotnet restore
dotnet build

If errors persist, compare your changes to the manual migration guide to identify missing steps.

📝 Example

Complete Example: Migrating IT-API-EXP-EXAMPLE

This example shows the complete workflow for migrating an experience API.

# 1. Verify prerequisites
dotnet --version   # 10.0.101
saif --version     # 3.0.5
aspire --version   # 13.1.0

# 2. Close all terminals and VS Code windows

# 3. Reopen VS Code in repository root
cd C:\repos\it-api-exp-example
code .

# 4. Initialize MCP in VS Code terminal
saif mcp init

# 5. Open Copilot Agent Chat
# - Click Copilot icon → Agent Chat tab
# - Select Claude Opus model
# - Type: /mcp.forge.migrate-to-v3

# 6. Monitor progress
# Copilot outputs:
# ✅ Task 0: Baseline Build complete
# ✅ Task 1: .NET 10 SDK verified
# ✅ Task 2: SAIF Tools updated
# ✅ Task 3: dotnet-outdated-tool installed
# ✅ Task 4: .NET 10 Upgrade complete
# ✅ Task 5: Package Updates complete
# ✅ Task 6: AppHost Changes complete
# ✅ Task 7: Infrastructure Restructuring complete
# ✅ Task 8: Terraform Variable Casing complete
# ✅ Task 9: Entra ID Migration complete
# ✅ Task 10: Pipeline Updates complete

# 7. Review changes
git status
git diff

# 8. Test locally
dotnet build
dotnet test
cd src/Example.AppHost
aspire run

# 9. Update Azure DevOps pipelines
# - Delete: it-api-exp-example-okta-appauth, it-api-exp-example-okta-appauth-pr
# - Delete: it-api-exp-example-okta-userauth, it-api-exp-example-okta-userauth-pr
# - Create: it-api-exp-example-auth-pr (from .azdo/azure-pipelines-auth-pr.yml)
# - Create: it-api-exp-example-auth (from .azdo/azure-pipelines-auth.yml)

# 10. Commit and create PR
git checkout -b migrate-to-forge-v3
git add .
git commit -m "Migrate to Forge v3.0"
git push origin migrate-to-forge-v3

Result:

  • Migration completed in ~35 minutes
  • All tests passing
  • PR ready for review with automated changes

🚀 Next Steps

After completing the migration:

Task Guide
Configure Entra ID app roles and scopes Security Configuration
Update TypeSpec definitions for auth Security Configuration
Test authentication in local environment Create JWT for Testing APIs
Deploy to development environment Run your updated pipelines in Azure DevOps
Review breaking changes Forge 3.0 Release Notes

🤖 About the SAIF MCP Server

The SAIF MCP (Model Context Protocol) server is a built-in feature of the SAIF CLI that provides AI assistants like GitHub Copilot with direct access to:

  • Forge documentation — Migration guides, how-tos, and reference material
  • Guided workflows — Pre-built prompts for common tasks (create application, add feature, troubleshoot, migrate)
  • Template information — Complete template metadata and parameter descriptions
  • CLI commands — Searchable command help and examples

How it works:

  1. saif mcp init creates a .vscode/mcp.json configuration file
  2. The MCP server runs locally and connects to GitHub Copilot via VS Code
  3. Copilot can invoke MCP tools and prompts using /mcp.forge.* syntax
  4. The server retrieves documentation from the live Forge docs site and caches it locally

Available MCP prompts:

  • /mcp.forge.create-application — Start a new project on the Golden Path
  • /mcp.forge.add-feature — Add features like Cosmos DB, events, or frontend
  • /mcp.forge.troubleshoot-issue — Debug common Forge issues
  • /mcp.forge.explain-architecture — Learn about Forge concepts
  • /mcp.forge.migrate-to-v3 — Automated migration from v2 to v3