Guia do desenvolvedor para servidores MCP hospedados (versão prévia)

Este guia aborda recursos, detalhes de configuração e requisitos para servidores MCP hospedados no Namespace do Conector. Para obter uma visão geral dos servidores MCP hospedados, consulte a visão geral dos servidores MCP hospedados.

Regiões com suporte

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

• Centro-oeste dos EUA
• Ásia Oriental
• EUA Central
• Europa Setentrional

Acesse o portal do Connector Namespace

Você gerencia servidores MCP hospedados e seus namespaces no portal do Namespace do Conector. Você pode acessá-lo de duas maneiras:

• Por meio do portal do Azure: abra um recurso de namespace provisionado no portal do Azure, o que leva você ao portal do Namespace do Conector desse namespace.
• Diretamente: acesse https://connectors.azure.com/ e selecione seu namespace.

Autenticação

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

Autenticação de entrada

A autenticação de entrada protege a conexão entre clientes MCP e o servidor hospedado. O namespace fornece autenticação baseada em OAuth com Microsoft Entra ID pronto para uso.

Autenticação de saída

A autenticação de saída protege a conexão entre o servidor hospedado e o serviço downstream com o qual ele interage. Os servidores dão suporte aos seguintes mecanismos:

Opções de identidade gerenciada

Ao usar a identidade gerenciada para autenticação de saída, você pode escolher:

• SAMI (identidade gerenciada atribuída pelo sistema): criada e atribuída automaticamente ao namespace quando você a habilita durante a criação do namespace. Vinculado ao ciclo de vida do namespace, o que significa que ele é excluído quando o namespace é excluído.
• User-assigned managed identity (UAMI): um recurso Azure autônomo que você cria e atribui ao namespace. Persiste de forma independente e pode ser reutilizado entre recursos.

Adicionar identidade gerenciada atribuída pelo usuário ao namespace

Ao usar uma UAMI, você deve adicionar essa identidade ao namespace. Caso contrário, o servidor não poderá se autenticar em serviços downstream.

Para adicionar uma UAMI ao namespace:

1. Vá para a instância do namespace no portal da Web.
2. Clique na guia Identidade no menu à esquerda.
3. Na seção Atribuído ao Usuário , clique no botão +Adicionar .
4. Pesquise a identidade gerenciada desejada e clique em Adicionar.
5. Clique em Salvar na parte superior direita para salvar a alteração.

Integração com o Application Insights

Você pode configurar o servidor para enviar logs e métricas para um recurso especificado do Application Insights. O fluxo de criação do servidor fornece uma maneira de configurar imediatamente após a criação. Se você perdeu isso, siga estas etapas:

1. Vá para a instância do namespace no portal da Web.
2. Clique em Habilitar monitoramento na seção Monitoramento .
3. Insira o cadeia de conexão do recurso do Application Insights e clique em Enable.

Para exibir logs do servidor:

1. Vá para o portal Azure e localize o recurso do Application Insights configurado.
2. No menu à esquerda, selecione Investigar > Pesquisa.
3. Defina o filtro hora local para o intervalo de tempo desejado. Exiba os registros como rastreamentos ou itens individuais.

Política de acesso

A configuração da política de acesso permite controlar quem tem acesso ao servidor MCP hospedado. Quando você cria um servidor, uma política é criada automaticamente para você. Você pode adicionar políticas para conceder a outras pessoas acesso ao servidor.

A política de acesso pode ser adicionada para usuários individuais ou um grupo. Para criar um grupo, consulte Gerenciar grupos no Microsoft Entra ID.

Para adicionar uma política de acesso:

1. Vá para a instância do namespace no portal da Web.
2. Clique na guia Conectores MCP no menu à esquerda e abra o servidor.
3. Dentro do servidor, clique na guia Políticas de Acesso na parte superior.
4. Clique no botão + Adicionar Política de Acesso .
5. Escolha o Tipo de principal desejado.
6. Insira a ID do objeto Principal, que você pode encontrar no centro de administração do Microsoft Entra.
7. Insira a ID do Locatário da sua assinatura.

Requisitos de implantação do servidor

A maioria dos servidores MCP hospedados são implantados sem artefatos adicionais. Selecione o servidor no catálogo e o namespace o provisiona. Alguns servidores exigem configuração extra durante a implantação.

SQL do Azure

O servidor MCP SQL do Azure é criado em Data API Builder (DAB). O DAB fornece uma camada de API de dados segura em seu banco de dados e expõe as entidades selecionadas como ferramentas MCP que os agentes podem chamar. Em vez de conectar agentes diretamente ao banco de dados, o servidor executa o DAB, que impõe as definições de entidade e as permissões por entidade especificadas, para que os agentes só possam acessar os dados e as operações que você expõe explicitamente.

Por isso, o SQL do Azure requer um arquivo de configuração do Data API builder (DAB) que define:

• A string de conexão com o banco de dados
• As entidades (tabelas/visões) a serem expostas
• Permissões para cada entidade

Para gerar esse arquivo, instale a CLI do DAB. Em seguida, execute o seguinte comando, habilitando apenas o MCP (já que o DAB também dá suporte a pontos de extremidade GRAPHQL e REST):

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

Dependendo do tipo de identidade gerenciada usada (para o servidor acessar o banco de dados), o cadeia de conexão usa uma forma diferente:

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 arquivo, você também precisa adicionar entidades e permissões relacionadas. O seguinte adiciona Books como exemplo:

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

Para obter detalhes sobre como configurar entidades e permissões, consulte a autorização do construtor de API de Dados.

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

Conceder acesso à identidade gerenciada

Após a implantação, conceda acesso de identidade gerenciada ao banco de dados. No portal Azure, execute o seguinte no editor Query do Banco de Dados SQL (conectado como administrador) para conceder permissões. Verifique se você escolheu a consulta correta para o 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 a identidade foi criada:

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

Artigos relacionados

• Visão geral dos servidores MCP hospedados
• Início Rápido: Criar um servidor MCP hospedado
• O que é o namespace do conector Azure?