Partilhar via

Tutorial: Alojar um servidor MCP no Azure Functions

Este artigo mostra-lhe como hospedar servidores remotos do Model Context Protocol (MCP) no Azure Functions. Também aprende a usar autenticação incorporada para configurar a autorização dos endpoints do servidor e proteger melhor as suas ferramentas de IA.

Existem duas formas de hospedar um servidor MCP remoto no Azure Functions:

Opção de servidor MCP Description Melhor para...
Servidor de extensão MCP Usa a extensão MCP Azure Functions para criar servidores MCP personalizados, onde o trigger da extensão permite definir os endpoints das suas ferramentas. Estes servidores são suportados em todas as linguagens Functions e são desenvolvidos, implementados e geridos como qualquer outra aplicação de funções. Quando já estás familiarizado com o Functions e o seu modelo de programação baseado em bindings.
Servidor auto-hospedado As funções podem alojar um projeto de servidor MCP criado usando os SDKs MCP padrão. Quando já construiu o seu servidor usando os SDKs oficiais do MCP e procura alojamento baseado em eventos, sem servidor e escalável no Azure.

Observação

A possibilidade de Azure Functions alojar servidores MCP que cria usando SDKs MCP oficiais está atualmente em pré-visualização.

Este tutorial cobre ambas as opções de servidores MCP suportadas pelas Funções. Seleciona o separador que melhor se adequa ao teu cenário.

Neste tutorial, utilizas o Visual Studio Code para:

  • Crie um projeto de servidor MCP usando a extensão MCP.
  • Executa e verifica o teu servidor MCP localmente.
  • Crie uma aplicação de funções no Azure.
  • Implemente o seu projeto de servidor MCP.
  • Ative a autenticação incorporada.

Importante

Este artigo atualmente suporta apenas C#, Python e TypeScript. Para concluir o início rápido, selecione um desses idiomas suportados na parte superior do artigo.

Este artigo suporta a versão 4 do modelo de programação Node.js para o Azure Functions.

Este artigo suporta a versão 2 do modelo de programação Python para o Azure Functions.

Pré-requisitos

Crie o seu projeto de servidor MCP

Usa o Visual Studio Code para criar localmente um projeto de servidor MCP na tua linguagem preferida.

  1. No Visual Studio Code, pressione F1 para abrir a paleta de comandos. Procure e execute o comando Azure Functions: Create New Project....

  2. Escolha o local do diretório para o espaço de trabalho do projeto e escolha Selecionar. Você deve criar uma nova pasta ou escolher uma pasta vazia para o espaço de trabalho do projeto. Não escolha uma pasta de projeto que já faça parte de um espaço de trabalho.

  1. Forneça as seguintes informações quando solicitado:

    Pronta Seleção
    Selecione um tipo de projeto Escolha C#.
    Selecione um tempo de execução do .NET Escolha .NET 8.0 LTS.
    Selecione um modelo para a primeira função do seu projeto Escolha MCP Tool trigger.
    Fornecer um nome de função Escreva McpTrigger.
    Fornecer um namespace Escreva My.Functions.
    Nível de autorização Escolha FUNCTION, que requer a chave de acesso ao ligar-se ao servidor MCP remoto.
    Selecione como gostaria de abrir o seu projeto Escolha Open in current window.

  1. Forneça as seguintes informações quando solicitado:

    Pronta Seleção
    Selecione um tipo de projeto Escolha TypeScript.
    Selecione um modelo para a primeira função do seu projeto Escolha MCP Tool trigger.
    Fornecer um nome de função Escreva mcpToolTrigger.
    Nível de autorização Escolha FUNCTION, que requer a chave de acesso ao ligar-se ao servidor MCP remoto.
    Selecione como gostaria de abrir o seu projeto Escolha Open in current window.

  1. Forneça as seguintes informações quando solicitado:

    Pronta Seleção
    Selecione um tipo de projeto Escolha Python.
    Selecione um interpretador Python para criar um ambiente virtual Escolha o seu interpretador Python preferido. Se uma opção não for mostrada, digite o caminho completo para o binário do Python.
    Selecione um modelo para a primeira função do seu projeto Escolha MCP Tool trigger.
    Nome da função que pretende criar Introduza mcp_trigger.
    Nível de autorização Escolha FUNCTION, que requer a chave de acesso ao ligar-se ao servidor MCP remoto.
    Selecione como gostaria de abrir o seu projeto Escolha Open in current window.

Com esta informação, o Visual Studio Code gera um projeto de código para um trigger de servidor MCP. Você pode exibir os arquivos de projeto locais no Explorer.

Iniciar o servidor MCP localmente

As aplicações funcionais precisam de um componente de armazenamento para correr. Antes de iniciar o servidor, inicie o emulador de armazenamento local:

  1. Em local.setting.json, certifique-se de que tem "AzureWebJobsStorage": "UseDevelopmentStorage=true".

  2. No Visual Studio Code, pressione F1 para abrir a paleta de comandos. Na paleta de comandos, procure e selecione Azurite: Start.

  3. Verifique a barra inferior e verifique se os serviços de emulação Azurite estão em execução. Se sim, agora pode correr o servidor localmente.

  4. Para começar a correr localmente, pressione F5.

As aplicações funcionais precisam de um componente de armazenamento para correr. Antes de iniciar o servidor, inicie o emulador de armazenamento local:

  1. Em local.setting.json, certifique-se de que tem "AzureWebJobsStorage": "UseDevelopmentStorage=true".

  2. No Visual Studio Code, pressione F1 para abrir a paleta de comandos. Na paleta de comandos, procure e selecione Azurite: Start.

  3. Verifique a barra inferior e verifique se os serviços de emulação Azurite estão em execução. Se sim, agora pode correr o servidor localmente.

  4. Para começar a correr localmente, pressione F5.

As aplicações funcionais precisam de um componente de armazenamento para correr. Antes de iniciar o servidor, inicie o emulador de armazenamento local:

  1. Em local.setting.json, certifique-se de que tem "AzureWebJobsStorage": "UseDevelopmentStorage=true".

  2. No Visual Studio Code, pressione F1 para abrir a paleta de comandos. Na paleta de comandos, procure e selecione Azurite: Start.

  3. Verifique a barra inferior e verifique se os serviços de emulação Azurite estão em execução. Se sim, agora pode correr o servidor localmente.

  4. Para começar a correr localmente, pressione F5.

Testa o servidor

  1. Encontre o .vscode diretório e abra mcp.json. O editor deve adicionar a informação de ligação do servidor.

  2. Inicie o servidor selecionando o botão Iniciar acima do nome do servidor.

  3. Quando se liga ao servidor, vê o número de ferramentas disponíveis acima do nome do servidor.

  4. Abre o chat do Copilot do Visual Studio Code no modo agente e depois faz uma pergunta. Por exemplo, "Cumprimente com #your-local-server-name". Esta pergunta garante que o Copilot usa o servidor para ajudar a responder à questão.

  5. Quando o Copilot solicitar a execução de uma ferramenta a partir do servidor MCP local, selecione Permitir.

  6. Desliga-te do servidor quando terminares o teste selecionando Parar, e Cntrl+C para parar de o executar localmente.

Sugestão

Na janela do chat do Copilot, selecione o ícone da ferramenta na parte inferior para ver a lista de servidores e ferramentas disponíveis para o chat. Certifique-se de que o servidor MCP local é verificado durante os testes.

Autorização remota de servidor MCP

Existem duas formas de reduzir ou prevenir o uso não autorizado dos seus endpoints remotos do servidor MCP:

Método Description
Autenticação de servidor incorporada (pré-visualização) As funcionalidades incluem autenticação e autorização incorporadas do App Service que implementam os requisitos OAuth do protocolo de especificação de autorização MCP. Os clientes que tentam aceder ao servidor são redirecionados para um fornecedor de identidade configurado, como o Microsoft Entra ID, para autenticação antes de poderem ligar-se. Este método proporciona o mais alto nível de segurança para os endpoints das suas ferramentas.
Autenticação baseada em chave Por defeito, o Functions implementa um requisito de chave de acesso para que os clientes que tentem usar ferramentas de servidor MCP tenham de apresentar um valor de chave secreta partilhada no cabeçalho do pedido. Embora não ofereça o mesmo nível de segurança da autenticação baseada em OAuth, as chaves de acesso dificultam o acesso a ferramentas públicas. Use um Anonymous nível de acesso para desativar chaves de acesso no seu servidor ao usar autenticação baseada em OAuth.

Observação

Este tutorial contém instruções detalhadas de configuração para a funcionalidade incorporada de autorização e autenticação de servidores, que também pode ser referida como Autenticação de Serviços de Aplicações noutros artigos. Pode encontrar uma visão geral da funcionalidade e algumas orientações de utilização no artigo Configurar autorização de servidor incorporada (pré-visualização ).

Desativar a autenticação baseada em chave

A funcionalidade de autorização de servidores incorporada é um componente separado do Azure Functions. Ao usar autenticação de servidor, é melhor primeiro desativar a autenticação baseada em chaves, permitindo o acesso anónimo.

Para desativar a autenticação baseada em host no seu servidor MCP, defina system.webhookAuthorizationLevel para Anonymous no host.json ficheiro:

{
  "version": "2.0",
  "extensions": {
    "mcp": {
      ...
      "system": {
        "webhookAuthorizationLevel": "Anonymous"
      }
    }    
  }
}

Criar o aplicativo de função no Azure

Cria uma aplicação de funções no plano Flex Consumption no Azure que aloje o teu servidor MCP.

  1. No portal do Azure, no menu ou na página inicial, selecione Criar um recurso.

  2. Selecione Introdução e, em seguida, Criar em Aplicativo de função.

  3. Em Selecione uma opção de hospedagem, escolha Flex Consumption>Select.

  4. Na página Noções básicas, use as configurações do aplicativo de função conforme especificado na tabela a seguir:

    Configuração Valor sugerido Description
    Subscription A sua subscrição A assinatura na qual você cria seu novo aplicativo de função.
    Grupo de Recursos myResourceGroup Nome para o novo grupo de recursos no qual você cria seu aplicativo de função.
    Função Nome do aplicativo Nome globalmente exclusivo Nome que identifica a sua nova aplicação de funções. Os carateres válidos são a-z (não sensível a maiúsculas e minúsculas), 0-9 e -.
    Região Região preferida Selecione uma região perto de você ou perto de outros serviços que suas funções possam acessar. As regiões sem suporte não são exibidas. Para obter mais informações, consulte Exibir regiões atualmente suportadas.
    Pilha de tempo de execução Língua preferida Escolha uma das pilhas de tempo de execução de linguagem suportadas. Atualmente, a edição no portal usando o Visual Studio Code for the Web só está disponível para aplicativos Node.js, PowerShell e Python. A biblioteca de classes C# e as funções Java devem ser desenvolvidas localmente.
    Versão Versão linguística Escolha uma versão suportada da sua pilha de tempo de execução de linguagem.
    Tamanho da instância Predefinido Determina a quantidade de memória de instância alocada para cada instância do seu aplicativo. Para obter mais informações, consulte Tamanhos de instância.

  5. Na página Armazenamento , aceite o comportamento padrão de criar uma nova conta de armazenamento de host padrão ou escolha usar uma conta de armazenamento existente.

  1. Na página Monitoramento , verifique se a opção Habilitar Application Insights está selecionada. Aceite o padrão para criar uma nova instância do Application Insights ou escolha usar uma instância existente. Ao criar uma instância do Application Insights, você também é solicitado a selecionar um espaço de trabalho do Log Analytics.

  2. Na página Autenticação , altere o Tipo de autenticação para Identidade gerenciada para todos os recursos. Com essa opção, também é criada uma identidade gerenciada atribuída pelo usuário que seu aplicativo usa para acessar esses recursos do Azure usando a autenticação de ID do Microsoft Entra. As identidades gerenciadas com o Microsoft Entra ID fornecem o mais alto nível de segurança para se conectar aos recursos do Azure.

  3. Aceite as opções predefinidas nos separadores restantes e, em seguida, selecione Rever + criar para rever a configuração da aplicação de que escolheu.

  4. Quando estiver satisfeito, selecione Criar para provisionar e implantar o aplicativo de função e os recursos relacionados.

  5. Selecione o ícone Notificações no canto superior direito do portal e observe a mensagem Implantação bem-sucedida .

  6. Selecione Ir para o recurso para ver a sua nova aplicação de funções. Você também pode selecionar Fixar no dashboard. A fixação facilita o acesso novamente a este recurso de aplicação de funções a partir do seu painel de controlo.

    Captura de tela da notificação de implantação.

Implementar o projeto de servidor MCP

Importante

A implementação numa aplicação de funções existente sempre sobrescreve o conteúdo dessa aplicação no Azure.

  1. Na paleta de comandos, insira e selecione Azure Functions: Deploy to Function App.

  2. Selecione o aplicativo de função que você acabou de criar. Quando for solicitado para substituir implantações anteriores, selecione Implantar para transferir o seu código de função para o novo recurso da aplicação de funções.

  3. Quando a implantação estiver concluída, selecione Exibir Saída para exibir os resultados da criação e da implantação, incluindo os recursos do Azure que você criou. Se você perder a notificação, selecione o ícone de sino no canto inferior direito para vê-lo novamente.

    Captura de ecrã da janela de saída de visualização.

  1. As aplicações Python também exigem que adicione esta definição de app:

    PYTHONPATH=/home/site/wwwroot/.python_packages/lib/site-packages.

Agora podes implementar o projeto do servidor:

Importante

A implementação numa aplicação de funções existente sempre sobrescreve o conteúdo dessa aplicação no Azure.

  1. Na paleta de comandos, insira e selecione Azure Functions: Deploy to Function App.

  2. Selecione o aplicativo de função que você acabou de criar. Quando for solicitado para substituir implantações anteriores, selecione Implantar para transferir o seu código de função para o novo recurso da aplicação de funções.

  3. Quando a implantação estiver concluída, selecione Exibir Saída para exibir os resultados da criação e da implantação, incluindo os recursos do Azure que você criou. Se você perder a notificação, selecione o ícone de sino no canto inferior direito para vê-lo novamente.

    Captura de ecrã da janela de saída de visualização.

Quando a implementação terminar, deverá ver uma notificação no Visual Studio Code sobre a ligação ao servidor. Selecione o botão Conectar para que o editor configure a informação de ligação ao servidor em mcp.json.

Ativar a autorização e autenticação do servidor incorporadas

A seguinte instrução mostra como ativar a funcionalidade de autorização e autenticação incorporada na aplicação servidor e configura o Microsoft Entra ID como fornecedor de identidade. Quando terminar, teste ligando-se ao servidor no Visual Studio Code e verá que lhe é solicitado autenticar-se antes de estabelecer a ligação.

Configurar autenticação na aplicação do servidor

  1. Abra a aplicação do servidor no portal Azure, e selecione Definições>Autenticação no menu esquerdo.

  2. Selecione Adicionar fornecedor> de identidadeMicrosoft como fornecedor de identidade.

  3. Para Escolher um tenant para a sua aplicação e os seus utilizadores, selecione Configuração de Workforce (tenant atual).

  4. Em Registo de aplicações: use estas definições:

    Configuração Seleção
    Tipo de inscrição na aplicação Criar novo registo de aplicação
    Nome Insira um nome descritivo para a sua aplicação
    Expiração da chave secreta do cliente Recomendado: 180 dias
    Tipos de conta suportados Inquilino atual - Inquilino único

  5. Em verificações adicionais:, para o requisito da aplicação cliente, selecione Permitir pedidos de aplicações cliente específicas, selecione o ícone do lápis, adicione o ID aebc6443-996d-45c2-90f0-388ff96faa56do cliente Visual Studio Code e selecione OK. Deixa as outras secções como estão.

  6. Nas definições de autenticação do App Service , use estas definições:

    Configuração Seleção
    Restringir o acesso Exigir autenticação
    Pedidos não autenticados HTTP 401 Não autorizado: recomendado para APIs
    Loja de tokens Assinala a caixa que permite a atualização dos tokens

  7. Selecione Adicionar. Depois de as definições se propagarem, deverá ver o seguinte resultado:

    Captura de ecrã das definições de autenticação do App Service a mostrar 'Requer autenticação' selecionada e 'HTTP 401 Unauthorized' definida para pedidos não autenticados.

Pré-autorizar o Visual Studio Code como cliente

  1. Selecione o nome da aplicação Entra ao lado da Microsoft. Esta ação leva-o ao recurso Visão Geral da aplicação Entra.

  2. No menu esquerdo, encontre Gerir -> Expor uma API.

  3. Em Aplicações cliente autorizadas, selecione +Adicionar uma aplicação cliente.

  4. Introduza o ID do cliente do Visual Studio Code: aebc6443-996d-45c2-90f0-388ff96faa56.

  5. Selecione a caixa em frente ao telescópio que se assemelhe a api://abcd123-efg456-hijk-7890123/user_impersonation.

  6. Selecione Adicionar aplicativo.

Configurar metadados de recursos protegidos (visualização)

  1. Na mesma visualização Expose a API, encontre a secção Scopes e copie o escopo que permite a administradores e utilizadores consentirem na aplicação Entra. Este valor assemelha-se a api://abcd123-efg456-hijk-7890123/user_impersonation.

  2. Execute o mesmo comando anterior para adicionar a definição WEBSITE_AUTH_PRM_DEFAULT_WITH_SCOPES:

    az functionapp config appsettings set --name <function-app-name> --resource-group <resource-group-name> --settings "WEBSITE_AUTH_PRM_DEFAULT_WITH_SCOPES=<scope>"

  3. Também na vista Expose a API , encontra o URI do ID da aplicação (que parece api://abcd123-efg456-hijk-7890123) no topo e guarda para o passo seguinte.

Liga-te ao servidor

Abre mcp.json dentro do .vscode diretório.

Quando seleciona Ligar no pop-up após a implementação, o Visual Studio Code preenche o ficheiro com a informação de ligação ao servidor.

Se falhares esse passo, também podes abrir o Output (Ctrl/Cmd+Shift+U) para encontrar o botão de ligação em linha no final dos registos de implementação.

Também pode adicionar manualmente informações de ligação:

  1. Obtenha o domínio do servidor executando o seguinte comando:

    az functionapp show --name <FUNCTION_APP_NAME> --resource-group <RESOURCE_GROUP_NAME> --query "defaultHostName" --output tsv

  2. No Visual Studio Code, abre a paleta de comandos, pesquisa e executa o comando MCP: Add Server... , e depois segue estes prompts:

    Pronta Sugestão
    Tipo de servidor a adicionar HTTP
    URL do teu servidor MCP https://<FUNCTION_APP_NAME>.azurewebsites.azurewebsites.net/runtime/webhooks/mcp
    Nome do servidor remote-mcp-server
    Onde instalar o servidor Workspace

  3. O Visual Studio Code abre o mcp.json ficheiro de definições para si.

Siga as instruções na secção seguinte para se ligar ao servidor, dependendo de como configurou a autenticação.

Com autenticação e autorização incorporadas

  1. Inicie o servidor remoto selecionando o botão Iniciar acima do nome do servidor.

  2. Quando questionado sobre autenticação com a Microsoft, selecione Permitir e depois inicie sessão com o seu email (o que é usado para iniciar sessão no portal Azure).

  3. Quando se liga com sucesso ao servidor, vê o número de ferramentas disponíveis acima do nome do servidor.

  4. Abre o chat do Copilot do Visual Studio Code no modo agente e depois faz uma pergunta. Por exemplo, Greet with #your-remote-mcp-server-name.

  5. Pare o servidor quando terminar os testes.

Para compreender em detalhe o que acontece quando o Visual Studio Code tenta ligar-se ao servidor MCP remoto, veja Protocolo de autorização do servidor.

Com chave de acesso

Se não ativar autenticação e autorização incorporadas e quiser ligar-se ao seu servidor MCP usando uma chave de acesso, deverá mcp.json conter a chave de acesso Functions nos cabeçalhos de pedido de um registo de servidor.

O Visual Studio preenche automaticamente a chave de acesso quando inicias o servidor.

O mcp.json ficheiro deve assemelhar-se ao seguinte exemplo:

{
	"servers": {
		"remote-mcp-server": {
			"type": "http",
			"url": "https://${input:functionapp-domain}/runtime/webhooks/mcp",
			"headers": {
				"x-functions-key": "${input:functions-key}"
			}
		}
	},
	"inputs": [
		{
			"type": "promptString",
			"id": "functions-key",
			"description": "Functions App Key",
			"password": true
		},
		{
			"type": "promptString",
			"id": "functionapp-domain",
			"description": "The domain of the function app.",
			"password": false
		}
	]
}

Se quiseres encontrar a chave de acesso por ti próprio, vai à aplicação Function no portal Azure. No menu esquerdo, encontre Funções -> Teclas de Aplicação. Na secção de chaves do Sistema, encontre a que se chama mcp_extension.

Sugestão

Para ver os registos de ligação, vá ao nome do servidor e selecione Mais>Mostrar Saída. Para mais detalhes sobre a interação entre o cliente (Visual Studio Code) e o servidor MCP remoto, selecione o ícone de engrenagem e escolha Trace.

Captura de ecrã das definições do servidor MCP que mostra o nível de registo _Trace_ selecionado.

Configure o agente Azure AI Foundry para usar as suas ferramentas

Pode configurar um agente no Azure AI Foundry para usar ferramentas expostas pelos servidores MCP alojados no Azure Functions.

  1. No portal Foundry, encontra o agente que queres configurar com servidores MCP alojados em Funções.

  2. Em Ferramentas, selecione o botão Adicionar e depois selecione + Adicionar uma nova ferramenta.

  3. Selecione a aba Personalizado e, em seguida, selecione Protocolo de Contexto de Modelo (MCP) e o botão Criar.

  4. Preencha as seguintes informações:

    • Nome: Nome do servidor
    • Endpoint remoto do servidor MCP:
      • Servidor de extensão MCP: https://<server domain>/runtime/webhooks/mcp
      • Servidor autoalojado: https://<server domain>/mcp
    • Autenticação: Escolha "Microsoft Entra"
    • Tipo: Escolha "Identidade Gerida por Projeto"
    • Audiência: Este é o URI de ID da aplicação Entra de Configurar metadados de recursos protegidos

    Por exemplo:

    Diagrama mostrando a configuração do agente Foundry para ligação ao servidor MCP.

  5. Selecione Conectar.

  6. Teste fazendo uma pergunta que possa ser respondida com a ajuda de uma ferramenta de servidor na janela de chat.

Protocolo de autorização de servidor

No resultado de depuração do Visual Studio Code, vê-se uma série de pedidos e respostas à medida que o cliente MCP e o servidor interagem. Quando utiliza a autorização do servidor MCP incorporada, vê a seguinte sequência de eventos:

  1. O editor envia um pedido de inicialização para o servidor MCP.
  2. O servidor MCP responde com um erro indicando que é necessária autorização. A resposta inclui um ponteiro para os metadados de recursos protegidos (PRM) da aplicação. A funcionalidade de autorização incorporada gera o PRM para a aplicação servidora.
  3. O editor recupera o PRM e usa-o para identificar o servidor de autorização.
  4. O editor tenta obter os metadados do servidor de autorização (ASM) a partir de um endpoint bem conhecido no servidor de autorização.
  5. Microsoft Entra ID não suporta ASM no endpoint conhecido, por isso o editor recorre a usar o endpoint de metadados OpenID Connect para obter o ASM. Tenta descobrir isto inserindo o ponto final bem conhecido antes de qualquer outra informação do caminho.
  6. As especificações OpenID Connect definiram, na verdade, o ponto final conhecido como sendo responsável pela informação do caminho, e é aí que o Microsoft Entra ID o aloja. Por isso, o editor tenta novamente com esse formato.
  7. O editor recupera com sucesso o ASM. Depois, utiliza esta informação juntamente com o ID de cliente próprio para realizar um início de sessão. Neste ponto, o editor pede-lhe que faça login e consinta com a candidatura.
  8. Assumindo que consegue iniciar sessão e consentir, o editor conclui a autenticação. Repete o pedido de iniciação para o servidor MCP, desta vez incluindo um token de autorização no pedido. Esta nova tentativa não é visível na saída de nível de Debug, no entanto, pode vê-la na saída de nível de Trace.
  9. O servidor MCP valida o token e responde com sucesso ao pedido de inicialização. O fluxo padrão de MCP continua a partir deste ponto, resultando, em última análise, na descoberta da ferramenta MCP definida nesta amostra.

Solução de problemas

Se tiveres problemas, pede ajuda ao GitHub Copilot. Aqui ficam algumas ideias específicas para resolução de problemas:

Não tenho mais ideias neste momento. Lembre-se de perguntar ao Copilot Chat sobre quaisquer erros que ocorram.

Próximos passos

Aprenda como registar servidores MCP alojados no Azure Functions no Azure API Center.

  • Last updated on