Gestire gli strumenti MCP usando un gateway di intelligenza artificiale (anteprima)

Controllare come gli agenti accedono agli strumenti esterni instradando il traffico MCP (Model Context Protocol) attraverso un gateway AI in Microsoft Foundry. Un gateway di intelligenza artificiale offre un singolo punto di ingresso regolamentato in cui è possibile applicare l'autenticazione, i limiti di frequenza, le restrizioni IP e la registrazione di controllo senza modificare i server MCP o il codice dell'agente.

Questa funzionalità è disponibile in anteprima. Solo i nuovi strumenti MCP creati nel portale foundry che non usano OAuth gestiti vengono instradati tramite un gateway di intelligenza artificiale.

Prerequisiti

• Il gateway di intelligenza artificiale deve essere connesso alla risorsa Microsoft Foundry. Seguire la procedura descritta in Configurare un gateway AI nelle risorse Foundry.

  La governance viene attivata a livello di risorsa Microsoft Foundry. Tutte le funzionalità di governance dipendono da questa connessione.

• Sono necessarie autorizzazioni per gestire i criteri di Gestione API: il ruolo Collaboratore del servizio Gestione API o Proprietario nell'istanza di Gestione API connessa. Per altre informazioni, vedere Usare il controllo degli accessi in base al ruolo per Gestione API.

• Il server MCP deve supportare uno dei metodi di autenticazione seguenti:

  • Identità gestita (Microsoft Entra)
  • Basato su chiave (chiave API o token)
  • Pass-through dell'identità OAuth personalizzata
  • Non autenticato (se applicabile)

Vantaggi principali

• Routing sicuro per tutti i nuovi strumenti MCP tramite un endpoint del gateway
• Controllo di accesso coerente e imposizione dell'autenticazione
• Osservabilità centralizzata per il traffico del gateway (ad esempio log e metriche)
• Criteri unificati per la gestione del flusso, le restrizioni IP e il routing
• Riutilizzo facile degli strumenti tramite cataloghi pubblici e privati

Gestire uno strumento

Le sezioni seguenti illustrano come configurare un gateway di intelligenza artificiale come punto di ingresso regolamentato.

Aggiungere uno strumento

Per aggiungere uno strumento da gestire, usare uno di questi metodi nel portale foundry:

• Usare il catalogo degli strumenti selezionando Catalogo strumenti>. Scegliere quindi un server MCP da aggiungere.
• Aggiungere uno strumento personalizzato selezionando Build>ToolsCustom> di contesto del modello>). Incollare quindi l'endpoint server MCP e selezionare un tipo di autenticazione.

Dopo aver aggiunto lo strumento, verificare che l'endpoint server MCP nella configurazione dello strumento visualizzi l'URL del gateway di intelligenza artificiale ,ad esempio , https://<your-API-Management-instance>.azure-api.net/mcp/...anziché l'URL del server MCP diretto.

Per altre informazioni sugli strumenti MCP, vedere Connettersi ai server del protocollo di contesto del modello.

Confermare il routing

Prima di applicare i criteri, verificare queste impostazioni nel portale foundry:

• Endpoint MCP del server remoto: verificare che faccia riferimento all'URL del gateway AI, non al server MCP originale.
• URL di reindirizzamento: se si usa il pass-through di identità OAuth personalizzato, verificare che l'URL di reindirizzamento corrisponda alla registrazione dell'app OAuth.
• Metodo di autenticazione: verificare che il metodo (basato su chiave o OAuth) sia allineato ai requisiti del server MCP.
• Utilizzo dell'agente: si noti quali agenti fanno riferimento a questo strumento in modo da poter eseguire test dopo l'applicazione dei criteri.

Applicare le politiche

Nel portale Azure, vai alla tua risorsa. Selezionare Gestione API per applicare i criteri per la governance.

È necessario applicare i criteri tramite Gestione API di Azure. I criteri comuni includono:

• Limitazione della frequenza: limitare il numero di chiamate che un progetto o un utente può effettuare in un minuto.

  <inbound>
    <base />
    <rate-limit-by-key calls="60" renewal-period="60" counter-key="@(context.Request.IpAddress)" />
  </inbound>
  

• Filtro IP: consente le richieste solo da reti attendibili.

  <inbound>
    <base />
    <ip-filter action="allow">
      <address>10.0.0.0/24</address> <!-- internal network -->
      <address>20.50.123.45</address> <!-- trusted app -->
    </ip-filter>
  </inbound> 
  

• ID correlazione: aggiungere un ID richiesta univoco in modo da poter tracciare le richieste in un secondo momento nei log.

  <inbound>
    <base />
      <set-header name="X-Correlation-Id" exists-action="override"> 
      <value>@(context.RequestId)</value>
    </set-header>
  </inbound>
  

• Rimozione di intestazioni sensibili: pulire le richieste in ingresso per proteggere le credenziali o i dati della sessione.

  <inbound>
    <base />
    <set-header name="Cookie" exists-action="delete" />
    <set-header name="Referer" exists-action="delete" />
  </inbound>
  

  Importante

  Evitare di eliminare le intestazioni di autenticazione ( ad esempio Authorization) a meno che non si sia certi che il server MCP non li richieda.

• Controllo di routing semplice: se si dispone di back-end diversi ,ad esempio quelli per aree geografiche diverse, è possibile instradare le richieste in base a un'intestazione.

  <inbound>
    <base />
    <choose>
      <when condition="@(context.Request.Headers.GetValueOrDefault('X-Region','us') == 'eu')">
        <set-backend-service base-url="https://europe-api.contoso-mcp.net" />
      </when>
      <otherwise>
        <set-backend-service base-url="https://us-api.contoso-mcp.net" />
      </otherwise>
    </choose>
  </inbound>
  

Per altri esempi XML dei criteri, vedere il repository dei frammenti di criteri di Gestione API su GitHub.

Eseguire il test con un agente

Dopo aver configurato il server MCP, è possibile testarlo nel portale foundry:

1. Aprire il portale Foundry e vai al tuo progetto.

2. Creare un nuovo agente o aprirne uno esistente e configurare uno strumento MCP. Per informazioni dettagliate, vedere Collegarsi ai server del protocollo di contesto del modello.

3. Nell'interfaccia di chat dell'agente, invia un messaggio che attiva lo strumento, ad esempio "Elenca i miei repository" per il server MCP di GitHub. Verificare che la risposta venga restituita con successo.

Verificare che la governance funzioni

Usare questi passaggi per verificare che il traffico venga instradato attraverso il gateway di intelligenza artificiale e vengano applicati i criteri:

1. Nel portale foundry aprire la configurazione dello strumento MCP. Verificare che l'endpoint dello strumento punti al gateway di intelligenza artificiale (non direttamente al server MCP).

2. Nel portale di Azure aprire l'istanza di Gestione API connessa alla risorsa Foundry. Esaminare le metriche e i log per verificare che le richieste vengano visualizzate quando l'agente chiama lo strumento.

Quando si esaminano le metriche di Gestione API:

• Cercare le richieste in cui il nome dell'istanza di Gestione API corrisponde allo strumento MCP.
• Controllare i codici di risposta per le chiamate riuscite (2xx) e le chiamate bloccate dai criteri (429 per i limiti di frequenza, 403 per i filtri IP).
• Se è stata applicata la limitazione della frequenza, verificare che l'intestazione X-RateLimit-Remaining diminuisca con ogni chiamata.
• Per informazioni dettagliate a livello di log, abilitare Impostazioni di diagnostica nell'istanza di Gestione API ed eseguire query sui log Monitoraggio di Azure.

Considerazioni sulla sicurezza

• Considerare le chiavi API, i token e i segreti client OAuth come segreti. Archiviare le credenziali condivise in una connessione al progetto e limitare l'accesso al progetto agli utenti autorizzati.
• Applicare il principio dei privilegi minimi per l'identità gestita e l'accesso Microsoft Entra.
• Rivedi quali intestazioni invii ai backend. Rimuovi solo le intestazioni che non sono necessarie ed evita di rimuovere le intestazioni di autenticazione richieste.

Per le opzioni di autenticazione MCP, vedere Configurare l'autenticazione per gli strumenti MCP (Model Context Protocol) (anteprima).

Risoluzione dei problemi

Limitazioni

• I gateway di intelligenza artificiale supportano solo gli strumenti MCP. Gli strumenti basati su Foundry, ad esempio SharePoint, gli strumenti MCP code-first, gli strumenti con OAuth gestito o gli strumenti OpenAPI non sono supportati.
• I gateway di intelligenza artificiale non registrano le tracce degli strumenti.
• Il routing del gateway viene applicato solo al momento della creazione dello strumento. Gli strumenti esistenti non vengono mediati automaticamente con i gateway di intelligenza artificiale.
• I gateway API supportano l'applicazione dei criteri di Gestione API solo nel portale di Azure, non nel portale foundry.

Per un elenco più ampio del supporto dello strumento di servizio Foundry Agent quando si lavora con i gateway, vedere Bring your own AI gateway to Azure AI Agent Service (preview).

Contenuto correlato

• Connettersi ai server del Model Context Protocol (anteprima)
• Configurare l'autenticazione per gli strumenti MCP (Model Context Protocol) (anteprima)
• Individuare e gestire gli strumenti nel catalogo degli strumenti Foundry (anteprima)