Quickstart: Criar um servidor MCP alojado no Espaço de Nomes do Conector (pré-visualização)

Implantar usando a CLI do Azure Developer

A forma mais fácil de implementar um servidor SQL MCP é ir ao exemplo azure-sql-mcp e seguir instruções README para implementar usando a CLI do Azure Developer ou azd. O exemplo contém ficheiros Bicep que lhe permitem aprovisionar um espaço de nomes do Connector, um servidor SQL MCP, uma base de dados SQL e outros recursos do Azure necessários com um único comando.

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

• Um servidor Base de Dados SQL do Azure com uma base de dados. Se não tiveres uma, cria uma base de dados SQL do Azure.

• CLI do Data API Builder (DAB) instalado.

Seed da base de dados SQL

1. No portal do Azure, vai à tua base de dados SQL (não ao servidor).

2. No menu esquerdo, selecione Editor de Consultas e inicie sessão como administrador da base de dados.

3. Selecione Nova consulta e execute o seguinte comando para semear a base 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 ficheiro de configuração DAB

O servidor MCP alojado em SQL é construído sobre o Data API Builder (DAB), que fornece uma API de dados segura sobre a sua base de dados e expõe as suas entidades (tabelas) como ferramentas MCP. O servidor requer um ficheiro de configuração DAB que defina a ligação à base de dados e as entidades a expor.

1. Gera um ficheiro de configuração DAB para a tua base de dados e ativa 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 acede à base de dados subjacente usando uma identidade gerida atribuída pelo sistema (SAMI), a cadeia de ligação deve assemelhar-se ao seguinte exemplo:

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

2. Adicionar a entidade Livros e a permissão associada:

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

   Para detalhes sobre a configuração de entidades e permissões, consulte Autorização do construtor de APIs de dados.

   Aqui está 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. Procure Playwright e selecione-o para criar o servidor.

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

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

8. Carrega o ficheiro de configuração DAB gerado anteriormente.

9. Selecione Criar.

Conceda à identidade do namespace acesso à sua base de dados

O servidor SQL alojado usa o SAMI do namespace para aceder à sua base de dados. Podes ativar um SAMI durante a criação do namespace.

Se não ativaste um SAMI durante a criação, tens de o ativar indo à instância do teu namespace no portal web. No menu à esquerda, localize o separador Identidade. Mude o alternador Atribuído pelo sistema para Ativado e guarde as alterações.

Vá à sua base de dados SQL no portal Azure, abra o editor de consultas e execute o seguinte comando para conceder acesso à identidade gerida:

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 de namespace do conector.

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

4. Abre o modo agente do Copilot e pergunta "Que tabelas estão disponíveis?"

4. Chame uma ferramenta específica. Por exemplo, o seguinte comando 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 seguinte comando chama a describe_entities ferramenta 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. Utilize a ferramenta read_records para recuperar registos 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'
   

Resolver o problema do SQL Server

Se o seu servidor SQL MCP alojado não se ligar ou não devolver dados como esperado, verifique os seguintes itens:

• ficheiro de configuração DAB. Confirme que o ficheiro de configuração DAB carregado é válido, usa a cadeia de ligação correta e define as entidades e permissões que espera expor.
• Identidade gerida atribuída ao sistema. Certifique-se de que um SAMI está ativado no namespace. Aceda à sua instância de espaço de nomes no portal da Web, selecione o separador Identidade e confirme que Atribuído pelo sistema está definido como Ativado.
• Acesso à base de dados. Certifique-se de que à identidade do namespace é concedido acesso à base de dados. Veja Conceder à identidade do namespace acesso à sua base de dados.