Esporre l'API REST nella gestione delle API come server MCP

SI APPLICA A: Sviluppatore | Basic | Basic v2 | Standard | Standard v2 | Premium | Premium v2

In Gestione API è possibile esporre un'API REST gestita in Gestione API come server MCP (Model Context Protocol) remoto usando il gateway di intelligenza artificiale predefinito. Esporre una o più operazioni API come strumenti che i client MCP possono chiamare usando il protocollo MCP.

Gestione API di Azure supporta anche l'integrazione sicura con i server compatibili con MCP esistenti: server degli strumenti ospitati all'esterno di Gestione API. Per altre informazioni, vedere Esporre un server MCP esistente.

Altre informazioni su:

• Supporto del server MCP in Gestione API
• Funzionalità del gateway AI

Limitazioni

• Gestione API supporta attualmente gli strumenti server MCP, ma non supporta le risorse MCP né i prompt.
• Gestione API attualmente non supporta le funzionalità del server MCP nelle aree di lavoro.

Prerequisiti

• Se non si dispone già di un'istanza Gestione API, completare la guida introduttiva seguente: Creare un'istanza di Gestione API di Azure. L'istanza deve trovarsi in uno dei livelli di servizio che supportano i server MCP.

• Assicurarsi che l'istanza gestisca un'API compatibile con HTTP (qualsiasi API importata come API REST, incluse le API importate dalle risorse di Azure) da esporre come server MCP. Per importare un'API di esempio, vedere Importare e pubblicare la prima API.

  Annotazioni

  Altri tipi di API in Gestione API che non sono compatibili con HTTP non possono essere esposti come server MCP.

• Se si abilita la registrazione diagnostica tramite Application Insights o Monitoraggio di Azure nell'ambito globale (tutte le API) per l'istanza del servizio Gestione API, impostare l'opzione Numero di byte di payload da registrare per la risposta del front-end su 0. Questa impostazione impedisce la registrazione imprevista dei corpi di risposta in tutte le API e garantisce il corretto funzionamento dei server MCP. Per registrare i payload in modo selettivo per API specifiche, configurare l'impostazione singolarmente nell'ambito dell'API, consentendo il controllo mirato sulla registrazione delle risposte.

• Per testare il server MCP, è possibile usare Visual Studio Code con accesso a GitHub Copilot o a strumenti come MCP Inspector.

Esporre l'API come server MCP

Seguire questa procedura per esporre un'API REST gestita in Gestione API come server MCP:

1. Nel portale di Azure passare all'istanza di Gestione API.
2. Nel menu a sinistra, in API, selezionare Server MCP>+ Crea server MCP.
3. Selezionare Esponi un'API come server MCP.
4. Nel server MCP back-end:
   1. Selezionare un'API gestita da esporre come server MCP.
   2. Selezionare una o più operazioni API da esporre come strumenti. È possibile selezionare tutte le operazioni o solo operazioni specifiche.

      Annotazioni

      In seguito è possibile aggiornare le operazioni esposte come strumenti nel pannello Strumenti del server MCP.

5. In Nuovo server MCP:
   1. Immettere un Nome per il server MCP in Gestione API.
   2. Facoltativamente, immettere una Descrizione per il server MCP.
6. Fare clic su Crea.

• Il server MCP viene creato e le operazioni API vengono esposte come strumenti.
• Il server MCP è elencato nel pannello Server MCP. La colonna Server URL mostra l'endpoint del server MCP da chiamare per il test o all'interno di un'applicazione client.

Configurare i criteri per il server MCP

Configurare uno o più criteri di Gestione API per gestire il server MCP. I criteri si applicano a tutte le operazioni API esposte come strumenti nel server MCP. Usare questi criteri per controllare l'accesso, l'autenticazione e altri aspetti degli strumenti.

Altre informazioni sulla configurazione dei criteri:

• Criteri di Gestione API
• Trasformare e proteggere l'API
• Impostare e modificare i criteri
• Proteggere l'accesso al server MCP

Attenzione

Non accedere al corpo della risposta usando la variabile context.Response.Body all'interno delle politiche del server MCP. In questo modo viene attivato il buffer delle risposte, che interferisce con il comportamento di streaming richiesto dai server MCP e potrebbe causare malfunzionamenti.

Per configurare i criteri per il server MCP, seguire questa procedura:

1. Nel portale di Azure passare all'istanza di Gestione API.

2. Nel menu a sinistra, in API, selezionare Server MCP.

3. Selezionare un server MCP dall'elenco.

4. Nel menu a sinistra, in MCP, selezionare Criteri.

5. Nell'editor dei criteri aggiungere o modificare i criteri da applicare agli strumenti del server MCP. Definire le politiche in formato XML.

   Ad esempio, è possibile aggiungere un criterio per limitare le chiamate agli strumenti del server MCP (in questo esempio, una chiamata per 60 secondi per sessione MCP).

   <!-- Rate limit tool calls by Mcp-Session-Id header -->
   <set-variable name="body" value="@(context.Request.Body.As<string>(preserveContent: true))" />
   <choose>
       <when condition="@(
           Newtonsoft.Json.Linq.JObject.Parse((string)context.Variables["body"])["method"] != null 
           && Newtonsoft.Json.Linq.JObject.Parse((string)context.Variables["body"])["method"].ToString() == "tools/call"
       )">
       <rate-limit-by-key 
           calls="1" 
           renewal-period="60" 
           counter-key="@(
               context.Request.Headers.GetValueOrDefault("Mcp-Session-Id", "unknown")
           )" />
       </when>
   </choose>
   

   

Annotazioni

Gestione API valuta i criteri configurati nell'ambito globale (tutte le API) prima di valutare i criteri nell'ambito del server MCP.

Convalidare e usare il server MCP

Usare un agente LLM conforme (ad esempio GitHub Copilot, Semantic Kernel o Copilot Studio) o un client di test (ad esempio curl) per chiamare l'endpoint MCP ospitato da Gestione API. Assicurarsi che la richiesta includa intestazioni e token appropriati e confermare il routing e la risposta corretti dal server MCP.

Suggerimento

Se si usa MCP Inspector per testare un server MCP gestito da Gestione API, usare la versione 0.9.0.

Aggiungere il server MCP in Visual Studio Code

In Visual Studio Code usare la chat di GitHub Copilot in modalità agente per aggiungere il server MCP e usare gli strumenti. Per informazioni generali sui server MCP in Visual Studio Code, vedere Usare server MCP in VS Code.

Per aggiungere il server MCP in Visual Studio Code:

1. Usare il comando MCP: Aggiungi server dal riquadro comandi.

2. Quando richiesto, selezionare il tipo di server HTTP (HTTP o Server Sent Events).

3. Immettere l'URL del server relativo al server MCP in Gestione API. Ad esempio, https://<apim-service-name>.azure-api.net/<api-name>-mcp/mcp per l'endpoint MCP.

4. Immettere un ID server di propria scelta.

5. Selezionare se salvare la configurazione nelle impostazioni dell'area di lavoro o nelle impostazioni utente.

   • Impostazioni dell'area di lavoro : la configurazione del server viene salvata in un .vscode/mcp.json file disponibile solo nell'area di lavoro corrente.

   • Impostazioni utente : la configurazione del server viene aggiunta al file globale settings.json ed è disponibile in tutte le aree di lavoro. La configurazione è simile alla seguente:

   

Aggiungere campi alla configurazione JSON per impostazioni come l'intestazione di autenticazione. L'esempio seguente illustra la configurazione per una chiave di sottoscrizione di Gestione API passata in un'intestazione come nel valore di input. Altre informazioni sul formato di configurazione

Usare gli strumenti in modalità agente

Dopo aver aggiunto un server MCP in Visual Studio Code, è possibile usare gli strumenti in modalità agente.

1. Nella chat di GitHub Copilot selezionare Modalità agente e selezionare il pulsante Strumenti per visualizzare gli strumenti disponibili.

   

2. Selezionare uno o più strumenti dal server MCP per essere disponibili nella chat.

   

3. Immettere una richiesta nella chat per richiamare lo strumento. Ad esempio, se è stato selezionato uno strumento per ottenere informazioni su un ordine, è possibile chiedere all'agente informazioni su un ordine.

   Get information for order 2
   

   Selezionare Continua per visualizzare i risultati. L'agente usa lo strumento per chiamare il server MCP e restituisce i risultati nella chat.

   Screenshot dei risultati della chat in Visual Studio Code.

Risoluzione dei problemi e problemi noti

Problema	Causa	Soluzione
401 Unauthorized errore dal back-end	Intestazione dell'autorizzazione non inoltrata	Se necessario, usare la set-header politica per collegare manualmente il token.
La chiamata API funziona in Gestione API ma non riesce nell'agente	URL di base non corretto o token mancante	Ricontrollare i criteri di sicurezza e l'endpoint
Il flusso del server MCP ha esito negativo quando i log di diagnostica sono abilitati	La registrazione del corpo della risposta o l'accesso al corpo della risposta tramite criteri interferisce con il trasporto MCP	Disabilitare la registrazione del corpo della risposta nell'ambito Tutte le API. Vedere Prerequisiti

Contenuti correlati

• Esempio: autorizzazione dei server MCP con metadati delle risorse protette (PRM)

• Esempio: proteggere i server MCP remoti con Gestione API di Azure (sperimentale)

• Lab di autorizzazione client MCP

• Usare l'estensione Gestione API di Azure per VS Code per importare e gestire le API

• Registrare e individuare server MCP remoti nel Centro API di Azure

• Esporre l'API REST in Gestione API come server MCP

• Esporre e gestire il server MCP esistente