Guia para programadores de servidores MCP alojados (pré-visualização)

Este guia abrange funcionalidades, detalhes de configuração e requisitos para servidores hospedados do Model Context Protocol (MCP) no Connector Namespace. Para uma visão geral dos servidores MCP alojados, veja Servidores MCP alojados no Espaço de Nomes do Conector.

Regiões suportadas

Durante a pré-visualização, os servidores MCP alojados estão disponíveis nas seguintes regiões:

• E.U.A. Centro-Oeste
• Ásia Leste
• E.U.A. Central
• Europa do Norte

Acesso ao portal do Connector Namespace

Geres os servidores MCP alojados e os seus namespaces no portal Connector Namespace. Pode aceder de duas formas:

• Através do portal Azure. Abra um recurso de namespace provisionado no portal Azure, que o liga ao portal Connector Namespace para esse namespace.
• Diretamente. Vai ao portal web e seleciona o teu namespace.

Authentication

Os servidores MCP alojados envolvem dois limites de autenticação.

Autenticação de entrada

A autenticação de entrada assegura a ligação entre os clientes MCP e o servidor alojado. O espaço de nomes disponibiliza autenticação baseada em OAuth com o Microsoft Entra ID.

Autenticação de saída

A autenticação de saída assegura a ligação entre o servidor alojado e o serviço a jusante com o qual interage. Os servidores suportam os seguintes mecanismos:

Opções de identidade gerida

Ao utilizar uma identidade gerida para autenticação de saída, escolha uma das seguintes opções:

• Identidade gerida atribuída ao sistema (SAMI). É criado e atribuído automaticamente a um namespace quando o ativas durante a criação do namespace. Está ligado ao ciclo de vida do namespace, por isso é eliminado quando o namespace é eliminado.
• Identidade gerida atribuída pelo utilizador (UAMI). Um recurso Azure autónomo que crias e atribuis ao namespace. Persiste de forma independente e pode ser reutilizada em vários recursos.

Passos para adicionar uma identidade gerida atribuída pelo utilizador ao seu espaço de nomes

Quando usa um UAMI, deve adicionar essa identidade ao namespace. Caso contrário, o servidor não consegue autenticar-se para serviços a jusante.

Para adicionar um UAMI ao seu espaço de nomes:

1. No portal web, vai à instância do namespace.

2. No menu esquerdo, selecione o separador Identidade .

3. Na secção Atribuído pelo Utilizador , selecione o botão +Adicionar .

4. Procure a identidade gerida desejada e depois selecione Adicionar.

5. Selecione Guardar no canto superior direito para guardar a alteração.

Integração com o Application Insights

Pode configurar o servidor para enviar logs e métricas para um recurso específico do Application Insights. O fluxo de criação de servidores fornece uma forma de configurar esta opção imediatamente após a criação. Se perdeu, siga estes passos:

1. No portal web, vai à instância do namespace.

2. Na secção Monitorização , selecione Ativar monitorização.

3. Introduza a cadeia de ligação do recurso Application Insights e depois selecione Enable.

Para visualizar os registos do servidor:

1. Vai ao portal do Azure e encontra o recurso Application Insights que configuraste.

2. No menu esquerdo, selecione Investigar>Pesquisa.

3. Defina o filtro de Hora Local para o intervalo de tempo desejado. Veja os registos como vestígios ou itens individuais.

Política de acesso

Ao configurar uma política de acesso, controla quem pode aceder ao seu servidor MCP alojado. Quando crias um servidor, o portal cria automaticamente uma política para ti. Pode adicionar políticas para conceder acesso a outros ao servidor.

Pode adicionar uma política de acesso para utilizadores individuais ou para um grupo. Para criar um grupo, veja Gerir grupos em Microsoft Entra ID.

Para adicionar uma política de acesso:

1. No portal web, vai à instância do namespace.

2. Selecione o separador MCP Connectors no menu esquerdo e abra o seu servidor.

3. Dentro do servidor, selecione o separador Políticas de Acesso .

4. Selecione o botão + Adicionar Política de Acesso .

5. Escolha o valor do Tipo Principal desejado.

6. Introduza o valor do ID do Objeto Principal . Pode encontrá-lo no centro de administração Microsoft Entra.

7. Introduza o valor do ID de Inquilino para a sua subscrição.

Requisitos de implementação de servidores

A maioria dos servidores MCP alojados é implementada sem artefactos extra. Seleciona-se o servidor no catálogo, e o namespace propõe-o. Alguns servidores requerem configuração extra durante a implementação.

SQL do Azure

O servidor SQL do Azure MCP é construído sobre o Data API builder (DAB). O DAB fornece uma camada segura de API de dados sobre a sua base de dados e expõe as entidades que seleciona como ferramentas MCP que os agentes podem chamar.

Em vez de ligar agentes diretamente à base de dados, o servidor executa DAB. O DAB aplica as definições de entidade e as permissões por entidade que especifica, pelo que os agentes só podem aceder aos dados e operações que expõe explicitamente.

O SQL do Azure requer um ficheiro de configuração DAB que defina:

• A cadeia de ligação à base de dados.
• As entidades (tabelas ou vistas) a expor.
• Permissões para cada entidade.

Para gerar este ficheiro, instale o DAB CLI. Depois, execute o seguinte comando para ativar apenas o MCP (porque o DAB também suporta endpoints GraphQL e REST):

dab init --database-type "mssql" --host-mode "Development" --graphql.enabled false --rest.enabled false --connection-string "<your-connection-string>"

A forma da cadeia de ligação depende do tipo de identidade gerida que utiliza para o servidor aceder à base de dados.

Server=<your-sql-server>.database.windows.net;Database=<your-database>;Authentication=Active Directory Default;Encrypt=True;TrustServerCertificate=False;

Server=<your-sql-server>.database.windows.net;Database=<your-database>;Authentication=Active Directory Managed Identity;User Id=<your-uami-client-id>;Encrypt=True;TrustServerCertificate=False;

Depois de gerar o ficheiro, também precisa de adicionar entidades e permissões relacionadas. O comando seguinte acrescenta Books como exemplo:

dab add Books --source "dbo.Books" --permissions "anonymous:*"

Para detalhes sobre a configuração de entidades e permissões, consulte a visão geral da autorização do Data API builder.

Carregue o ficheiro de configuração gerado (exemplo) durante a implementação do servidor no portal do namespace.

Conceder acesso de identidade gerida

Após a implementação, conceda à identidade gerida acesso à base de dados. No portal Azure, execute o seguinte comando no editor de consultas para a base de dados SQL (iniciado como administrador) para conceder permissões. Certifique-se de escolher a consulta correta para o seu tipo de identidade.

CREATE USER [<your-connector-namespace-name>] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [<your-connector-namespace-name>];
ALTER ROLE db_datawriter ADD MEMBER [<your-connector-namespace-name>];
GRANT VIEW DEFINITION TO [<your-connector-namespace-name>];

CREATE USER [<your-uami-name>] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [<your-uami-name>];
ALTER ROLE db_datawriter ADD MEMBER [<your-uami-name>];
GRANT VIEW DEFINITION TO [<your-uami-name>];

Para verificar se criou a identidade:

SELECT name, type_desc, authentication_type_desc
FROM sys.database_principals
WHERE type IN ('E', 'X')
ORDER BY name;
-- Expected: <identity-name> | EXTERNAL_USER | EXTERNAL

Conteúdo relacionado

• Visão geral dos servidores MCP alojados
• Início rápido: Criar um servidor MCP alojado
• O que é o namespace do conector?