Início Rápido: Criar um servidor MCP hospedado no Namespace do Conector do Azure (versão prévia)

• Um servidor Banco de Dados SQL do Azure com um banco de dados. Se você não tiver um, criar um banco de dados SQL do Azure.

• CLI do DAB (Construtor de API de Dados) instalada.

Propagar o banco de dados SQL

1. No portal Azure, navegue até o Banco de Dados SQL (not o servidor).

2. No menu à esquerda, clique no editor de Consultas e entre como administrador do banco de dados.

3. Clique em Nova consulta e execute o seguinte para propagar o banco de dados:

   CREATE TABLE dbo.Books
   (
      Id int IDENTITY(1,1) PRIMARY KEY,
      Title nvarchar(200) NOT NULL
   );
   
   INSERT INTO dbo.Books (Title) VALUES (N'The little prince');
   INSERT INTO dbo.Books (Title) VALUES (N'Pride and prejudice');
   

Gerar o arquivo de configuração do DAB (Construtor de API de Dados)

O servidor MCP hospedado pelo SQL é criado no DAB (Construtor de API de Dados), que fornece uma API de dados segura em seu banco de dados e expõe suas entidades (tabelas) como ferramentas MCP. O servidor requer um arquivo de configuração do DAB que define a conexão de banco de dados e as entidades a serem expostas.

1. Gere um arquivo de configuração do DAB para seu banco de dados, habilitando apenas o MCP:

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

   Como o servidor acessará o banco de dados subjacente usando uma SAMI (identidade gerenciada atribuída pelo sistema), o cadeia de conexão deve ser semelhante ao seguinte:

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

2. Adicione a entidade Books e a permissão relacionada:

   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.

   Exemplo de arquivo de configuração:

   {
      "$schema": "https://github.com/Azure/data-api-builder/releases/download/v1.7.93/dab.draft.schema.json",
      "data-source": {
         "database-type": "mssql",
         "connection-string": "Server=<your-sql-server>.database.windows.net;Database=<your-database>;Authentication=Active Directory Default;Encrypt=True;TrustServerCertificate=False;",
         "options": {
            "set-session-context": false
         }
      },
      "runtime": {
         "rest": {
            "enabled": false,
            "path": "/api",
            "request-body-strict": true
         },
         "graphql": {
            "enabled": false,
            "path": "/graphql",
            "allow-introspection": true
         },
         "mcp": {
            "enabled": true,
            "path": "/mcp"
         },
         "host": {
            "cors": {
               "origins": [],
               "allow-credentials": false
            },
            "authentication": {
               "provider": "AppService"
            },
            "mode": "development"
         }
      },
      "entities": {
         "Books": {
            "source": {
               "object": "dbo.Books",
               "type": "table"
            },
            "graphql": {
               "enabled": true,
               "type": {
                  "singular": "Books",
                  "plural": "Books"
               }
            },
            "rest": {
               "enabled": true
            },
            "permissions": [
               {
                  "role": "anonymous",
                  "actions": [
                     {
                     "action": "*"
                     }
                  ]
               }
            ]
         }
      }
   }
   

6. Pesquise o Dramaturgo e clique para criar o servidor.

6. Pesquise SQL do Azure e clique para criar o servidor.

7. Na janela de criação, selecione Gerenciar Identidade para Método de Autenticação de Saída.

8. Carregue o arquivo de configuração do DAB gerado anteriormente.

9. Clique em Criar.

Conceder acesso à identidade do namespace ao banco de dados

O SQL Server hospedado usa a SAMI (identidade gerenciada) atribuída pelo sistema do namespace para acessar seu banco de dados, que você pode habilitar durante a criação do namespace.

Se você não habilitou o SAMI durante a criação, deverá habilitá-lo acessando sua instância de namespace no portal da Web. No menu à esquerda, localize a guia Identidade . Alterne o sistema atribuído a Ativado e salve a atualização.

Vá para o banco de dados SQL no portal do Azure, abra o editor Query e execute o seguinte para conceder acesso à identidade gerenciada:

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>];

Substitua <your-namespace-name> pelo nome do recurso Namespace do conector.

4. Abra o modo de agente do Copilot, pergunte "Qual é a pizzaria mais próxima perto da 11 Times Square?"

4. Abra o modo de agente do Copilot, pergunte "Quais tabelas estão disponíveis?"

4. Chame uma ferramenta específica. Por exemplo, a seguir é feita uma chamada para a ferramenta browser_navigate:

   npx @modelcontextprotocol/inspector --cli \
   "<your-mcp-endpoint-url>" \
   --transport http \
   --method tools/call \
   --tool-name browser_navigate \
   --tool-arg url="https://www.google.com/search?q=pizza+near+11+Times+Square+New+York" \
   --header "Authorization: Bearer $MCP_TOKEN"
   

4. Chame uma ferramenta específica. Por exemplo, o seguinte usa a ferramenta describe_entities para listar as entidades disponíveis:

   npx @modelcontextprotocol/inspector --cli \
   "<your-mcp-endpoint-url>" \
   --transport http \
   --method tools/call \
   --header "Authorization: Bearer $MCP_TOKEN" \
   --tool-name describe_entities \
   --tool-arg 'nameOnly=true'
   

5. Chame a read_records ferramenta para recuperar registros de uma entidade (Books):

   npx @modelcontextprotocol/inspector --cli \
   "<your-mcp-endpoint-url>" \
   --transport http \
   --method tools/call \
   --header "Authorization: Bearer $MCP_TOKEN" \
   --tool-name read_records \
   --tool-arg 'entity=Books' \
   --tool-arg 'first=2'
   

Solucionar problemas do SQL Server

Se o servidor MCP do SQL hospedado não conectar ou retornar dados conforme o esperado, verifique o seguinte:

• DAB configuration file: confirme se o arquivo de configuração DAB carregado é válido, usa o cadeia de conexão correto e define as entidades e permissões que você espera expor.
• IDENTIDADE gerenciada atribuída pelo sistema (SAMI): verifique se o SAMI está habilitado no namespace. Vá para a instância do namespace no portal da Web, selecione a guia Identidade e confirme se o Sistema Atribuído está definido como Ativado.
• Acesso ao banco de dados: verifique se a identidade do namespace recebeu acesso ao banco de dados. Confira Conceder acesso à identidade do namespace ao banco de dados.