Avvio rapido: Crea un server MCP ospitato nello spazio dei Connector (anteprima)

Distribuire utilizzando Azure Developer CLI

Il modo più semplice per distribuire un server SQL MCP è andare all'esempio azure-sql-mcp e seguire le istruzioni README per distribuire usando la CLI Azure Developer o azd. L'esempio contiene file biceps che permettono di fornire un Connector Namespace, un server SQL MCP, un database SQL e altre risorse Azure necessarie con un solo comando.

Se preferisci implementare un server SQL MCP e le risorse richieste dall'inizio alla fine, segui le istruzioni qui sotto.

• Un server di database SQL di Azure con un database. Se non è disponibile, creare un database Azure SQL.

• Data API builder (DAB) CLI installato.

Inizializzare il database SQL

1. Nel portale di Azure passare al database SQL (non al server).

2. Nel menu a sinistra selezionare Editor di query e accedere come amministratore del database.

3. Selezionare Nuova query ed eseguire il comando seguente per eseguire il seeding del database:

   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');
   

Generare il file di configurazione DAB

Il server MCP ospitato da SQL è basato su Data API Builder (DAB), che fornisce un'API dati sicura sul database ed espone le relative entità (tabelle) come strumenti MCP. Il server richiede un file di configurazione DAB che definisce la connessione al database e le entità da esporre.

1. Generare un file di configurazione DAB per il database e abilitare solo MCP:

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

   Poiché il server accede al database sottostante utilizzando un'identità gestita assegnata dal sistema (SAMI), la stringa di connessione dovrebbe assomigliarsi al seguente esempio:

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

2. Aggiungere l'entità Books e l'autorizzazione correlata:

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

   Per informazioni dettagliate sulla configurazione di entità e autorizzazioni, vedere Autorizzazione del generatore di API dati.

   Ecco un file di configurazione di esempio:

   {
      "$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. Cercare Playwright e selezionarlo per creare il server.

6. Cerca SQL MCP Server e selezionalo per creare il server.

7. Nella finestra di creazione selezionare Gestisci identità per il metodo di autenticazione in uscita.

8. Caricare il file di configurazione DAB generato in precedenza.

9. Fare clic su Crea.

Concedere all'identità dello spazio dei nomi l'accesso al database.

Il server SQL ospitato usa l'istanza SAMI dello spazio dei nomi per accedere al database. È possibile abilitare un SAMI durante la creazione dello spazio dei nomi.

Se non hai abilitato un SAMI durante la creazione, devi abilitarlo accedendo all'istanza del namespace nel portale Web. Nel menu a sinistra individuare la scheda Identità . Impostare l'interruttore Assegnato dal sistema su Sì e salvare l'aggiornamento.

Passare al database SQL nel portale di Azure, aprire l'editor di query ed eseguire il comando seguente per concedere l'accesso all'identità gestita:

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

Sostituisci <your-connector-namespace-name> con il nome della risorsa Namespace del connettore.

4. Apri la modalità agente di Copilot e chiedi: "Qual è la pizzeria più vicina a 11 Times Square?"

4. Apri la modalità agente di Copilot e chiedi "Quali tabelle sono disponibili?"

4. Chiamare uno strumento specifico. Ad esempio, il comando seguente chiama lo browser_navigate strumento:

   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. Chiamare uno strumento specifico. Ad esempio, il comando seguente chiama lo describe_entities strumento per elencare le entità disponibili:

   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. Chiama lo strumento read_records per recuperare i record di un'entità (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'
   

Risolvere i problemi relativi a SQL Server

Se il server MCP SQL ospitato non si connette o restituisce dati come previsto, controllare gli elementi seguenti:

• File di configurazione DAB. Verificare che il file di configurazione DAB caricato sia valido, usi il stringa di connessione corretto e definisca le entità e le autorizzazioni che si prevede di esporre.
• Identità gestita assegnata dal sistema. Assicurarsi che un SAMI sia abilitato nello spazio dei nomi. Vai all'istanza dello spazio dei nomi nel portale Web, seleziona la scheda Identità e verifica che Assegnata dal sistema sia impostato su On.
• Accesso al database. Assicurarsi che all'identità dello spazio dei nomi sia concesso l'accesso al database. Vedere Concedere all'identità dello spazio dei nomi l'accesso al database.