Guida introduttiva: Integrare il server MCP di Azure con GitHub Copilot SDK

Questa guida illustra come configurare GitHub Copilot SDK per l'uso degli strumenti MCP (Model Context Protocol) di Azure per interagire con le risorse di Azure.

Azure MCP offre un set di strumenti che consentono agli assistenti di intelligenza artificiale di interagire direttamente con le risorse di Azure. Se integrato con Copilot SDK, è possibile creare applicazioni che sfruttano il linguaggio naturale per gestire sottoscrizioni, gruppi di risorse, account di archiviazione e altro ancora.

Prerequisiti

• GitHub Copilot CLI installato.
• Node.js installato (per l'esecuzione del server tramite npx).
• Interfaccia della riga di comando di Azure installata e autenticata (az login).

Accedere al server MCP di Azure per lo sviluppo locale

Il server MCP di Azure esegue l'autenticazione con Microsoft Entra ID usando la libreria di identità di Azure per .NET. Il server supporta due modalità di autenticazione:

• Modalità Broker: usa l'autenticazione nativa del sistema operativo (ad esempio Gestione Account Web di Windows) con InteractiveBrowserCredential.
• Modalità catena di credenziali: prova più metodi di autenticazione in sequenza: variabili di ambiente, Visual Studio Code, Visual Studio, interfaccia della riga di comando di Azure, Azure PowerShell, interfaccia della riga di comando per sviluppatori di Azure e autenticazione interattiva del browser.

Accedere usando uno dei metodi seguenti:

Visual Studio Code

1. Aprire il riquadro comandi (Ctrl+Shift+P o Cmd+Shift+P su Mac).
2. Eseguire Azure: accedere e seguire le istruzioni.

Visual Studio

1. Vai a File > Impostazioni account.
2. Selezionare Aggiungi un account e seguire le istruzioni.

CLI di Azure

az login

Azure PowerShell

Connect-AzAccount

CLI per sviluppatori di Azure

azd auth login

Dopo l'accesso, il server MCP di Azure può autenticare ed eseguire operazioni sui servizi di Azure in base alle autorizzazioni.

Esempio di configurazione del server MCP di Azure

Indipendentemente dall'SDK di programmazione usato, il server MCP di Azure deve essere configurato nel contesto dell'app per rendere disponibili gli strumenti. La configurazione essenziale è simile alla seguente:

{
  "mcp_servers": {
    "azure-mcp": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@azure/mcp@latest", "server", "start"],
      "tools": ["*"]
    }
  }
}

Il tools: ["*"] parametro è essenziale: consente tutti gli strumenti del server MCP per la sessione.

Esempi di integrazione

Gli esempi seguenti illustrano come integrare l'SDK in linguaggi diversi.

Annotazioni

Per un avvio più rapido, è possibile installare il server MCP di Azure a livello globale usando npm install -g @azure/mcp@latest.

Python

Installazione

Installare il pacchetto Python SDK usando pip.

pip install github-copilot-sdk

Esempio di codice

Il codice seguente illustra un flusso completo:

import asyncio
from copilot import CopilotClient
from copilot.generated.session_events import SessionEventType

async def main():
    # Initialize the Copilot client
    client = CopilotClient({
        "cli_args": [
            "--allow-all-tools",
            "--allow-all-paths",
        ]
    })

    await client.start()

    # Configure Azure MCP server in session config
    azure_mcp_config = {
        "azure-mcp": {
            "type": "local",
            "command": "npx",
            "args": ["-y", "@azure/mcp@latest", "server", "start"],
            "tools": ["*"],  # Enable all Azure MCP tools
        }
    }

    # Create session with MCP servers
    session = await client.create_session({
        "model": "gpt-4.1",  # Default model; BYOK can override
        "streaming": True,
        "mcp_servers": azure_mcp_config,
    })

    # Handle events
    def handle_event(event):
        if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
            if hasattr(event.data, 'delta_content') and event.data.delta_content:
                print(event.data.delta_content, end="", flush=True)
        elif event.type == SessionEventType.TOOL_EXECUTION_START:
            tool_name = getattr(event.data, 'tool_name', 'unknown')
            print(f"\n[TOOL: {tool_name}]")

    session.on(handle_event)

    # Send prompt
    await session.send_and_wait({
        "prompt": "List all resource groups in my Azure subscription"
    })

    await client.stop()

if __name__ == "__main__":
    asyncio.run(main())

Il codice precedente:

• Inizializza il client Copilot.
• Configura il server MCP di Azure usando npx.
• Crea una sessione con il modello GPT-4.1 e lo streaming abilitati.
• Gestisce gli eventi per stampare le risposte dell'assistente e i log di esecuzione degli strumenti.
• Invia un prompt per elencare i gruppi di risorse di Azure.

Node.js/TypeScript

Installazione

Installare il pacchetto Node.js SDK usando npm.

npm install @github/copilot-sdk

Il codice seguente illustra un flusso completo:

import { CopilotClient } from '@github/copilot-sdk';
import type { MCPLocalServerConfig } from '@github/copilot-sdk';

async function main() {
  // Initialize the Copilot client
  const client = new CopilotClient({
    cliArgs: [
      '--allow-all-tools',
      '--allow-all-paths',
    ]
  });

  await client.start();

  // Configure Azure MCP server in session config
  const azureMcpConfig: Record<string, MCPLocalServerConfig> = {
    'azure-mcp': {
      type: 'local',
      command: 'npx',
      args: ['-y', '@azure/mcp@latest', 'server', 'start'],
      tools: ['*'],  // Enable all Azure MCP tools
    }
  };

  // Create session with MCP servers
  const session = await client.createSession({
    model: 'gpt-4.1',  // Default model; BYOK can override
    streaming: true,
    mcpServers: azureMcpConfig,
  });

  // Handle events
  session.on((event) => {
    if (event.type === 'assistant.message_delta') {
      if (event.data?.deltaContent) {
        process.stdout.write(event.data.deltaContent);
      }
    } else if (event.type === 'tool.execution_start') {
      const toolName = event.data?.toolName || 'unknown';
      console.log(`\n[TOOL: ${toolName}]`);
    }
  });

  // Send prompt
  await session.sendAndWait({
    prompt: 'List all resource groups in my Azure subscription 16caa5c4-46f1-4bfd-8c1b-a99f1efc8845'
  });

  await client.stop();
}

main().catch(console.error);

Il codice precedente:

• Inizializza il client Copilot.
• Configura il server MCP di Azure usando npx.
• Crea una sessione con il modello GPT-4.1 e lo streaming abilitati.
• Gestisce gli eventi per stampare le risposte dell'assistente e i log di esecuzione degli strumenti.
• Invia un prompt per elencare i gruppi di risorse di Azure.

.NET

Installazione

Aggiungere il contenuto del pacchetto NuGet al progetto.

dotnet add package GitHub.Copilot.SDK

Esempio di codice

Il codice C# seguente illustra un flusso completo:

using GitHub.Copilot.SDK;

// Initialize the Copilot client
await using var client = new CopilotClient(new CopilotClientOptions
{
    CliArgs = new[] { "--allow-all-tools", "--allow-all-paths" }
});

await client.StartAsync();

// Configure Azure MCP server in session config
var mcpServers = new Dictionary<string, object>
{
    ["azure-mcp"] = new McpLocalServerConfig
    {
        Type = "local",
        Command = "npx",
        Args = ["-y", "@azure/mcp@latest", "server", "start"],
        Tools = ["*"]  // Enable all Azure MCP tools
    }
};

// Create session with MCP servers
await using var session = await client.CreateSessionAsync(new SessionConfig
{
    Model = "gpt-4.1",  // Default model; BYOK can override
    Streaming = true,
    McpServers = mcpServers
});

// Handle events
session.On(evt =>
{
    if (evt is AssistantMessageDeltaEvent delta)
    {
        if (!string.IsNullOrEmpty(delta.Data.DeltaContent))
        {
            Console.Write(delta.Data.DeltaContent);
        }
    }
    else if (evt is ToolExecutionStartEvent toolStart)
    {
        Console.WriteLine($"\n[TOOL: {toolStart.Data.ToolName}]");
    }
});

// Send prompt
await session.SendAndWaitAsync(new MessageOptions
{
    Prompt = "List all resource groups in my Azure subscription"
});

Il codice precedente:

• Inizializza il client Copilot.
• Configura il server MCP di Azure usando npx.
• Crea una sessione con il modello GPT-4.1 e lo streaming abilitati.
• Gestisce gli eventi per stampare le risposte dell'assistente e i log di esecuzione degli strumenti.
• Invia un prompt per elencare i gruppi di risorse di Azure.

Go

Installazione

Ottenere il pacchetto Go SDK usando go get.

go get github.com/github/copilot-sdk/go

Esempio di codice

Il codice seguente illustra un flusso completo:

package main

import (
    "context"
    "fmt"
    "log"

    copilot "github.com/github/copilot-sdk/go"
)

func main() {
    ctx := context.Background()

    // Initialize the Copilot client
    client, err := copilot.NewClient(copilot.ClientOptions{
        CLIArgs: []string{
            "--allow-all-tools",
            "--allow-all-paths",
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    if err := client.Start(ctx); err != nil {
        log.Fatal(err)
    }
    defer client.Stop(ctx)

    // Configure Azure MCP server in session config
    azureMcpConfig := map[string]copilot.MCPServerConfig{
        "azure-mcp": {
            Type:    "local",
            Command: "npx",
            Args:    []string{"-y", "@azure/mcp@latest", "server", "start"},
            Tools:   []string{"*"}, // Enable all Azure MCP tools
        },
    }

    // Create session with MCP servers
    session, err := client.CreateSession(ctx, copilot.SessionConfig{
        Model:      "gpt-4.1",  // Default model; BYOK can override
        Streaming:  true,
        MCPServers: azureMcpConfig,
    })
    if err != nil {
        log.Fatal(err)
    }

    // Handle events
    session.OnEvent(func(event copilot.SessionEvent) {
        switch event.Type {
        case copilot.AssistantMessageDelta:
            if event.Data.DeltaContent != "" {
                fmt.Print(event.Data.DeltaContent)
            }
        case copilot.ToolExecutionStart:
            fmt.Printf("\n[TOOL: %s]\n", event.Data.ToolName)
        }
    })

    // Send prompt
    err = session.SendAndWait(ctx, copilot.Message{
        Prompt: "List all resource groups in my Azure subscription",
    })
    if err != nil {
        log.Fatal(err)
    }
}

Il codice precedente:

• Inizializza il client Copilot.
• Configura il server MCP di Azure usando npx.
• Crea una sessione con il modello GPT-4.1 e lo streaming abilitati.
• Gestisce gli eventi per stampare le risposte dell'assistente e i log di esecuzione degli strumenti.
• Invia un prompt per elencare i gruppi di risorse di Azure.