Esporre e gestire un server MCP esistente

Questo articolo illustra come usare Gestione API per esporre e gestire un server MCP (Model Context Protocol) remoto esistente, un server di strumenti ospitato all'esterno di Gestione API. Esporre e gestire gli strumenti del server tramite Gestione API in modo che i client MCP possano chiamarli usando il protocollo MCP.

Gli scenari di esempio includono:

Server degli strumenti Proxy LangChain o LangServe tramite Gestione API con limiti di velocità e autenticazione per server.
Esporre in modo sicuro gli strumenti basati su App per la logica di Azure ai copiloti usando il filtro IP e OAuth.
Centralizzare gli strumenti server MCP da Funzioni di Azure e i runtime open source nel Centro API di Azure.
Abilitare GitHub Copilot, Claude by Anthropic o ChatGPT per interagire in modo sicuro con gli strumenti nell'azienda.

Gestione API supporta anche server MCP esposti in modo nativo in Gestione API dalle API REST gestite. Per altre informazioni, vedere Esporre un'API REST come server MCP.

Altre informazioni su:

Limitazioni

Il server MCP esterno deve essere conforme alla versione MCP 2025-06-18 o successiva. Il server può supportare:
- Nessuna autorizzazione o protocolli di autorizzazione conformi agli standard seguenti: https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#standards-compliance.
- Tipi di trasporto HTTP o SSE trasmissibili in streaming.
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 esiste ancora un'istanza di Gestione API, completare l'avvio rapido seguente: Creare un'istanza di Gestione API di Azure. L'istanza deve trovarsi in uno dei livelli di servizio che supportano i server MCP.
Accesso a un server compatibile con MCP esterno, ad esempio ospitato in App per la logica di Azure, Funzioni di Azure, LangServe o altre piattaforme.
Credenziali appropriate per il server MCP, ad esempio credenziali client OAuth 2.0 o chiavi API, a seconda del server, per l'accesso sicuro.
Se si abilita la registrazione diagnostica tramite Application Insights o Monitoraggio di Azure nell'ambito globale (tutte le API) per l'istanza di Gestione API, impostare a 0 l'opzione Numero di byte di payload da registrare per Risposta front-end. 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, usare Visual Studio Code con accesso a GitHub Copilot o a uno strumento come MCP Inspector.

Esporre un server MCP esistente

Seguire questa procedura per esporre un server MCP esistente in Gestione API:

Nel portale di Azure passare all'istanza di Gestione API.
Nel menu a sinistra, in API, selezionare Server MCP>+ Crea server MCP.
Selezionare Esponi un server MCP esistente.
In Server MCP back-end:
1. Immettere l'URL di base del server MCP esistente. Ad esempio, https://learn.microsoft.com/api/mcp per il server MCP di Microsoft Learn.
2. In Tipo di trasporto è selezionato HTTP streamable per impostazione predefinita.
In Nuovo server MCP:
1. Immettere un nome per il server MCP in Gestione API.
2. In Percorso base, immettere un prefisso di route per gli strumenti. Ad esempio: mytools.
3. Facoltativamente, immettere una Descrizione per il server MCP.
Fare clic su Crea.

Screenshot della creazione di un server MCP nel portale.

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

Importante

Gestione API attualmente non visualizza gli strumenti dal server MCP esistente. È necessario registrare e configurare tutti gli strumenti nel server MCP remoto esistente.

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:

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:

Nel portale di Azure passare all'istanza di Gestione API.
Nel menu a sinistra, in API, selezionare Server MCP.
Selezionare un server MCP dall'elenco.
Nel menu a sinistra, in MCP, selezionare Criteri.

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, oppure un client di test, ad esempio curl, per chiamare l'endpoint MCP ospitato da Gestione API. Assicurarsi che la richiesta includa intestazioni o 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:

Usare il comando MCP: Aggiungi server dal riquadro comandi.
Quando richiesto, selezionare il tipo di server HTTP (HTTP o Server Sent Events).
Immettere l'URL server del server MCP in Gestione API. Ad esempio, https://<apim-service-name>.azure-api.net/<api-name>-mcp/mcp per l'endpoint MCP.
Immettere un ID server a scelta.
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

Schermata della configurazione dell'intestazione di autenticazione per un server MCP

Usare gli strumenti in modalità agente

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

Nella chat di GitHub Copilot selezionare Modalità agente e selezionare il pulsante Strumenti per visualizzare gli strumenti disponibili.
Selezionare uno o più strumenti dal server MCP per essere disponibili nella chat.
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
Errore `401 Unauthorized` 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	Verificare attentamente i criteri di sicurezza e l'endpoint
Il flusso del server MCP non riesce quando sono abilitati i log di diagnostica	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 di tutte le API. Vedere Prerequisiti

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-11-20