Início Rápido: Crie um servidor MCP hospedado no Espaço de Nomes do Conector (prévia)

Implantar usando Azure Developer CLI

A maneira mais fácil de implantar um servidor SQL MCP é acessar o exemplo azure-sql-mcp e seguir instruções do README para implantar usando a CLI do Azure Developer ou azd. O exemplo contém arquivos Bicep que permitem provisionar um namespace do conector, um servidor SQL MCP, um banco de dados SQL e outros recursos necessários do Azure com apenas um comando.

Se você preferir implementar um servidor SQL MCP e os recursos necessários do início ao fim, siga as instruções abaixo.

• 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, acesse o banco de dados SQL (não o servidor).

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

3. Selecione Nova consulta e execute o seguinte comando 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

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 e habilite 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 acessa o banco de dados subjacente usando uma identidade gerenciada atribuída pelo sistema (SAMI), a cadeia de conexão deve se parecer com o seguinte exemplo:

   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.

   Veja um 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 selecione-o para criar o servidor.

6. Procure por SQL MCP Server e selecione para criar o servidor.

7. Na janela de criação, selecione Gerenciar Identidade para o método de autenticação de saída.

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

9. Selecione Criar.

Conceder acesso à identidade do namespace ao banco de dados

O SQL Server hospedado usa o SAMI do namespace para acessar seu banco de dados. Você pode habilitar um SAMI durante a criação do namespace.

Se você não habilitou um 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. Altere a opção Atribuído pelo sistema para Ativado e salve a alteração.

Acesse o banco de dados SQL no portal do Azure, abra o editor de Consultas e execute o seguinte comando 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-connector-namespace-name> pelo nome do recurso Namespace do conector.

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

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

4. Chame uma ferramenta específica. Por exemplo, o comando a seguir chama a browser_navigate ferramenta:

   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 comando a seguir chama a describe_entities ferramenta para listar 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 os seguintes itens:

• Arquivo de configuração do DAB. Confirme se o arquivo de configuração do 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. Verifique se um 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 tem acesso ao banco de dados. Confira Conceder acesso à identidade do namespace ao banco de dados.