Configurare l'MCP predefinito del servizio app (anteprima)

Il servizio app integrato MCP trasforma un'API REST esistente ospitata in Servizio app di Azure in un server MCP (Model Context Protocol (MCP) senza scrivere o distribuire codice MCP. La piattaforma legge una specifica OpenAPI specificata e genera uno strumento MCP per ogni operazione. Espone quindi l'endpoint MCP tramite HTTP streamable in un percorso a scelta.

Quando usare mcp predefinito

Usare MCP predefinito quando:

• Si dispone già di un'API REST in esecuzione nel servizio app e si vuole esponirla a un client di intelligenza artificiale compatibile con MCP (GitHub Copilot Chat, Cursor, Wind, Claude Desktop) senza modifiche al codice.
• Hai una specifica OpenAPI 3.0.x (JSON o YAML) che descrive le operazioni che vuoi esporre.
• Si vuole che la piattaforma gestisca la negoziazione del protocollo MCP, l'individuazione degli strumenti, il ricaricamento rapido della specifica e l'annullamento del client.
• Si desidera che l'autenticazione di App Service imponga l'identità per le richieste MCP, allo stesso modo in cui la impone per qualsiasi altro percorso dell'app.

Usa invece un server MCP personalizzato (sviluppato con un SDK MCP e distribuito come codice applicativo) quando:

• È necessario un comportamento dello strumento MCP che non esegue il mapping pulito a una singola operazione REST, ad esempio flussi di lavoro in più passaggi, aggregazioni in memoria o strumenti che non dispongono di un endpoint di backup HTTP.
• È necessario esporre risorse MCP o prompt oltre agli strumenti.
• È necessario ospitare più server MCP in una singola app.

Per un confronto di tutte le opzioni di hosting MCP in Azure, vedere Scegliere un servizio di Azure per il server MCP.

Prerequisiti

• Un'app di App Service in un livello tariffario dedicato (Basic o superiore). MCP integrato non è supportato nei piani Free, Shared, Consumption o Flex Consumption.
• Una specifica OpenAPI 3.0.x (JSON o YAML) che descrive le operazioni che vuoi esporre come strumenti MCP. Vedere Passaggio 1: Specificare la specifica OpenAPI per le opzioni di generazione.

Passaggio 1: Specificare la specifica OpenAPI

L'MCP integrato richiede un documento OpenAPI 3.0.x (JSON o YAML). La maggior parte dei framework Web può produrre uno per l'utente:

• ASP.NET Core API minime: usare il pacchetto predefinito Microsoft.AspNetCore.OpenApi (impostazione predefinita in .NET 9 e versioni successive).
• ASP.NET Core controller: usare Swashbuckle.
• FastAPI: generato automaticamente in /openapi.json.
• Express/NestJS: usare @nestjs/swagger o express-openapi.
• Spring Boot: usare springdoc-openapi.
• Java/Quarkus: usare SmallRye OpenAPI.

Se l'API è già in esecuzione ed espone un endpoint OpenAPI, non è necessario aggiungere una nuova libreria, scaricare la specifica da tale endpoint (ad esempio, con curl) e salvarla in locale in modo da poterla caricare quando si abilita MCP predefinito.

Una specifica minima che espone un'operazione è simile alla seguente:

{
  "openapi": "3.0.3",
  "info": { "title": "Zava Orders", "version": "1.0.0" },
  "paths": {
    "/orders/{id}": {
      "get": {
        "operationId": "get_order",
        "summary": "Get an order by ID",
        "parameters": [
          { "name": "id", "in": "path", "required": true,
            "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "OK" }
        }
      }
    }
  }
}

Usare valori chiari e orientati alle operationId azioni (list_orders, create_order, cancel_order). Il client di intelligenza artificiale li usa come nomi degli strumenti quando si sceglie quale strumento chiamare. Per informazioni dettagliate su come le operazioni corrispondono agli strumenti MCP, consulta Come fa MCP integrato a mappare le operazioni REST agli strumenti MCP?.

Rendere disponibile la specifica per la piattaforma

La piattaforma legge la specifica da un file nel file system dell'app. Il percorso predefinito è /home/data/.ai/apispec.json, configurabile tramite ApiSpecPath. La modalità di recupero del file dipende dal percorso di configurazione usato nel passaggio 2:

• Portale: caricare il file JSON o YAML quando si crea il server MCP. Il portale scrive il contenuto in ApiSpecPath per te.
• interfaccia della riga di comando di Azure: distribuisci la specifica con l'app (ad esempio, includila nell'artefatto di distribuzione) oppure caricala successivamente con az webapp deploy o az webapp ssh.
• Bicep: fare riferimento a un percorso che la distribuzione inserisce nell'app.

Passaggio 2: Abilitare mcp predefinito

L’MCP integrato viene configurato tramite la proprietà aiIntegration sulla risorsa Microsoft.Web/sites. L'anteprima viene fornita con Portal, interfaccia della riga di comando di Azure (usando az rest) e Bicep come percorsi di configurazione supportati.

Gli esempi seguenti mostrano il payload minimo per esporre ogni operazione della tua specifica. Per filtrare le operazioni, configurare l'autenticazione senza usare App Service Authentication o modificare la posizione della specifica, consulta Personalizzare l'MCP predefinito.

RESOURCE_GROUP=<resource-group>
APP_NAME=<app-name>
SUBSCRIPTION=$(az account show --query id -o tsv)
API_VERSION=2025-05-01

az rest \
  --method PATCH \
  --uri "https://management.azure.com/subscriptions/$SUBSCRIPTION/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.Web/sites/$APP_NAME?api-version=$API_VERSION" \
  --body '{
    "properties": {
      "aiIntegration": {
        "Mcp": {
          "Servers": [
            { "Name": "orders", "Endpoint": "/mcp/orders" }
          ]
        }
      }
    }
  }'

az rest \
  --method PATCH \
  --uri "https://management.azure.com/subscriptions/$SUBSCRIPTION/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.Web/sites/$APP_NAME?api-version=$API_VERSION" \
  --body '{ "properties": { "aiIntegration": null } }'

resource site 'Microsoft.Web/sites@2025-05-01' = {
  name: appName
  location: location
  properties: {
    serverFarmId: appServicePlanId
    aiIntegration: {
      Mcp: {
        Servers: [
          {
            Name: 'orders'
            Endpoint: '/mcp/orders'
          }
        ]
      }
    }
  }
}

Passaggio 3: Connettere un client MCP

Dopo aver salvato la configurazione, l'endpoint MCP è disponibile all'indirizzo:

https://<app-name>.azurewebsites.net/<endpoint path you provided>

Configurare il client MCP con tale URL. Ad esempio, in GitHub Copilot Chat in Visual Studio Code aggiungerlo a .vscode/mcp.json:

{
  "servers": {
    "my-mcp-server": {
      "type": "http",
      "url": "https://<app-name>.azurewebsites.net/<endpoint path you provided>"
    }
  }
}

Quando il client si connette, chiama initialize, quindi tools/list per individuare le operazioni esposte dalla specifica OpenAPI, quindi tools/call per ogni chiamata.

Authentication

McP predefinito non rilascia token o implementa un server di autorizzazione. App Service Authentication impone l'identità sulla stessa app e funziona con qualsiasi provider di identità supportato da App Service Authentication (Microsoft Entra e qualsiasi altro provider OpenID Connect (OIDC) configurato). Sono supportate due configurazioni:

• L'autenticazione del servizio app è abilitata (scelta consigliata). Le richieste MCP passano attraverso gli stessi controlli di identità di qualsiasi altra route e la piattaforma pubblica metadati delle risorse protette in /.well-known/oauth-protected-resource modo che i client MCP possano completare automaticamente OAuth. Completamento obbligatorio: completare la procedura descritta in Configurare l'autorizzazione del server MCP predefinita per registrare il gruppo di destinatari e gli ambiti MCP con il provider di identità.
• L'autenticazione del servizio app non è abilitata. Fornire i metadati del provider di identità in un blocco SiteAuth in aiIntegration. Questa opzione si adatta ai casi in cui si convalidano già i token nel codice dell'applicazione e non si vuole che l'autenticazione del servizio app gestisca il flusso OAuth per conto dell'app. Vedi Configurare l'autenticazione senza l'autenticazione di App Service.

In entrambi i casi, il codice dell'applicazione rimane responsabile della convalida del token bearer a ogni richiesta. McP predefinito non applica l'autorizzazione alle route HTTP sottostanti.

Personalizzare MCP integrato

Il payload minimo nel passaggio 2 accetta ogni impostazione predefinita. Aggiungere solo i campi necessari. Ogni frammento mostra il campo aggiunto sopra il payload minimo.

Modificare la posizione in cui si trova la specifica

Per impostazione predefinita, la piattaforma legge la specifica da /home/data/.ai/apispec.json. Impostare ApiSpecPath per leggerlo da un'altra posizione:

"aiIntegration": {
  "ApiSpecPath": "/home/site/wwwroot/openapi/orders.yaml",
  "Mcp": { "Servers": [ { "Name": "orders", "Endpoint": "/mcp/orders" } ] }
}

Filtra quali operazioni sono esposte

ToolList su ogni server determina quali operazioni OpenAPI il server MCP espone. Il valore predefinito è ["*"] (ogni operazione presente nella specifica).

• ["*"]— esporre ogni operazione contenuta nella specifica.
• []: non espongono alcuna operazione. Utile per disabilitare temporaneamente l'individuazione degli strumenti senza rimuovere il server.
• ["get_order", "list_orders"]: espone solo i valori elencati operationId .

"Mcp": {
  "Servers": [
    {
      "Name": "orders",
      "Endpoint": "/mcp/orders",
      "ToolList": ["get_order", "list_orders"]
    }
  ]
}

Usa questo filtro per mantenere le operazioni distruttive o riservate agli amministratori fuori dall'interfaccia MCP, continuando comunque a renderle disponibili ai client HTTP esistenti.

ToolList interagisce con gli aggiornamenti delle specifiche come indicato di seguito:

• ToolList = ["*"]— quando la specifica viene aggiornata, le nuove operazioni vengono esposte automaticamente.
• ToolList = ["op1", "op2"]— quando la specifica viene aggiornata, solo op1 e op2 vengono esposte. Le nuove operazioni nella specifica vengono ignorate fino a quando non vengono aggiunte a ToolList.
• Gli ID delle operazioni presenti in ToolList che non esistono nella specifica vengono eliminati senza alcuna segnalazione.

Se si desidera applicare solo filtri basati su specifiche (nessun elenco di elementi consentiti sul lato ARM), mantenere ToolList = ["*"] e rimuovere le operazioni dalla specifica stessa.

Disabilitare un server senza rimuoverlo

Impostare Enabled su false per portare offline l'endpoint MCP senza eliminare la configurazione:

"Mcp": {
  "Servers": [
    { "Name": "orders", "Endpoint": "/mcp/orders", "Enabled": false }
  ]
}

Configurare l'autenticazione senza autenticazione del servizio app

Quando l'autenticazione del servizio app non è abilitata nell'app, aggiungere un SiteAuth blocco in modo che la piattaforma possa pubblicare i metadati delle risorse protette in /.well-known/oauth-protected-resource. I client MCP (ad esempio VS Code) seguono l'intestazione WWW-Authenticate restituita nella prima chiamata per individuare il server di autorizzazione e completare il flusso OAuth.

"aiIntegration": {
  "Mcp": { "Servers": [ { "Name": "orders", "Endpoint": "/mcp/orders" } ] },
  "SiteAuth": {
    "Scopes": ["api://my-app/user_impersonation"],
    "WellKnownOpenIdConfiguration": "https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration",
    "Audience": "api://my-app-client-id"
  }
}

Campi obbligatori: Scopes, più WellKnownOpenIdConfiguration o Issuer. JwksUri e Audience sono facoltativi. Vedere Riferimento: schema aiIntegration per l'elenco completo dei campi.

Il codice dell'applicazione rimane responsabile della convalida del bearer token a ogni richiesta.

Registrare il server MCP nel Centro API di Azure

È possibile registrare il server MCP predefinito come asset in Azure Centro API per tenere traccia di tutte le API in una posizione centralizzata per l'individuazione, il riutilizzo e la governance. La registrazione è facoltativa: mcp predefinito funziona senza di essa, ma è il modo consigliato per mantenere visibili i server MCP insieme al resto del patrimonio API.

Il portale rende la registrazione un processo con un'unica selezione:

1. Nella scheda Server MCP espandere il server.

2. Accanto a Azure API Center, selezionare + Connetti.

   

3. Nel riquadro Connetti centro API scegliere una sottoscrizione e un Centro API esistente oppure selezionare Crea nuovo per crearne uno nuovo. Il servizio app compila i valori predefiniti (tipo, fase del ciclo di vita, ambiente, distribuzione) per conto dell'utente, in modo che non sia necessario configurarli manualmente.

4. Selezionare Connetti. Il dettaglio del server ora è collegato all'asset del Centro API.

Per modificare i metadati degli asset (tipo, fase del ciclo di vita, versione, proprietà personalizzate, definizioni, distribuzioni), modificare l'asset direttamente nel Centro API. Per registrare un server MCP in Centro API senza passare da App Service, oppure per registrarne uno che l'MCP integrato di App Service non ha creato, vedere Registrare e individuare i server MCP remoti nell'inventario API.

Per disconnettere il server MCP dal Centro API, eliminare l'asset server MCP corrispondente nel Centro API. Il collegamento nella scheda Server MCP di App Service si cancella una volta rimosso l'asset.

Troubleshooting

Il client MCP ottiene un valore 404 nell'endpoint configurato.

• Verificare che il Endpoint valore inizi con / e non sia in conflitto con una route esistente nell'app.
• Verificare che il campo Enabled del server sia true.

Il client MCP si connette ma tools/list restituisce una matrice vuota.

• Confermare che una specifica tecnica sia configurata, ovvero caricata tramite il portale oppure disponibile nel percorso impostato in ApiSpecPath.
• Verificare che ToolList non sia impostato su [].
• Validare la specifica con un linter OpenAPI 3.0.x - le operazioni che mancano di campi richiesti (come uno schema di risposta) vengono saltate.

Il client MCP ottiene un 401 con un problema WWW-Authenticate.

• Questo errore è previsto quando l'autenticazione del servizio app è abilitata e il client non ha un token valido. La richiesta di verifica indirizza il client all'endpoint dei metadati della risorsa protetta, che a sua volta rimanda al fornitore di identità. Vedere Configurare l'autorizzazione del server MCP predefinita.

Il client MCP riceve un errore 403 da una chiamata a uno strumento, ma tools/list va a buon fine.

• Il token OAuth è valido per l'individuazione MCP, ma non ha l'ambito o il ruolo richiesto dall'applicazione per la route HTTP sottostante. Controllare lo stato HTTP upstream visualizzato nell'oggetto CallToolResult.

Domande frequenti

In che modo le operazioni REST predefinite vengono mappate agli strumenti MCP?

Ogni operazione OpenAPI diventa uno strumento MCP:

• Nome dello strumento, derivato dall'oggetto dell'operazione operationId. Se operationId manca, la piattaforma esegue il fallback a {method}_{path} (ad esempio, get__orders__id_). Usare valori espliciti orientati alle operationId azioni per assegnare al client di intelligenza artificiale nomi più chiari degli strumenti.

• Descrizione dello strumento—prima quella dell'operazione summary, quindi description se manca summary.

• Annotazioni dello strumento—MCP integrato associa il metodo HTTP alle annotazioni dello strumento MCP:

  Metodo HTTP	readOnlyHint	idempotentHint	destructiveHint
  GET, HEAD	true	true	false
  PUT, PATCH	false	true	false
  DELETE	false	true	true
  POST	false	false	false

In che modo la piattaforma gestisce gli aggiornamenti delle specifiche?

Quando la specifica in ApiSpecPath cambia, sia perché hai ridistribuito il file sia perché hai caricato una nuova versione tramite il portale, la piattaforma:

1. Rileva la modifica.
2. Analizza nuovamente la specifica e ricalcola l'elenco degli strumenti.
3. Esegue l'hash del nuovo elenco di strumenti (SHA-256) e lo confronta con l'hash precedente.
4. Se l'hash è stato modificato, invia un notifications/tools/list_changed evento a ogni client MCP connesso.

Non è necessario riavviare l'app o aggiornare la aiIntegration configurazione per selezionare le modifiche specifiche. Per sapere come ToolList interagisce con gli aggiornamenti delle specifiche, vedere Filtrare le operazioni esposte.

A cosa serve la piattaforma in /.well-known/oauth-protected-resource?

La piattaforma pubblica i metadati delle risorse protette in modo che i client MCP possano individuare dove ottenere un token di accesso. Il contenuto proviene da:

• Autenticazione di App Service, se abilitata per l'app. La piattaforma pubblica i metadati del provider di identità configurato.
• Il blocco SiteAuth su aiIntegration, quando l'autenticazione di App Service non è abilitata. Vedi Configurare l'autenticazione senza l'autenticazione di App Service.

Se nessuno dei due elementi è configurato, la piattaforma non pubblica l'endpoint e i client non vengono sfidati per OAuth.

Quali sono i limiti?

Riferimento: schema aiIntegration

Passaggi successivi

• Configurare l'autorizzazione del server MCP predefinita
• Chiamate MCP sicure da Visual Studio Code con autenticazione Microsoft Entra
• Servizio app come server MCP (Model Context Protocol)
• Scegliere un servizio di Azure per il server MCP