Server MCP personalizzati

Costruisci un server MCP su Databricks Apps così il tuo agente può chiamare i tuoi strumenti. Databricks Apps fornisce le risorse di calcolo per eseguire il server e un URL HTTPS per permettere agli agenti di connettersi.

Scegliere il percorso

Scegli uno di questi tre modi per ospitare un server MCP su Databricks Apps:

Costruisci un server dal template Starter

Il template MCP Server (Starter) include uno strumento di controllo integrità funzionante che puoi chiamare prima di aggiungere il tuo codice Python.

Passo 1: Trova e implementa il modello

Usa uno spazio di lavoro che soddisfi i requisiti delle app Databricks.

  1. Nel tuo spazio di lavoro, apri Unity Gateway e seleziona MCP.
  2. Clicca su + MCP e scegli Crea un nuovo server MCP. Si apre la pagina di creazione delle app Databricks.
  3. Trova Installa da un modello. In questa galleria di modelli, seleziona la scheda Agenti, poi MCP Server (Starter).
  4. Rivedi le impostazioni di risorsa, calcolo e autorizzazione. Clicca su Avanti per continuare la configurazione.
  5. Nomina l'app mcp-my-server e clicca su Crea app. Usa un altro nome che inizi con mcp- se quel nome è già in uso. Questo prefisso permette a AI Playground di riconoscere il server MCP.

La creazione dell'app distribuisce anche il codice template. Aspetta che il deployment finisca nella pagina Panoramica dell'app; qui trovi il suo URL e lo stato del deployment.

Passo 2: Chiama il primo tool

Copia l'URL dell'app dalla sua pagina Panoramica e aggiungi /mcp:

https://<app-hostname>/mcp

Collega il tuo agente con questo URL.

Chiedi al tuo agente: "Richiama lo strumento health." Conferma che lo strumento restituisca "status": "healthy".

Passo 3: Aggiungi il tuo strumento

Aggiungi uno strumento che converte il testo in maiuscolo:

  1. Nella pagina Panoramica dell'app, fai clic su Modifica nel tuo IDE per copiare il codice sorgente sul computer e sincronizzare le modifiche di nuovo allo spazio di lavoro.

  2. server/tools.py aperti. Aggiungi questa funzione all'interno di load_tools(mcp_server), insieme agli strumenti esistenti:

        @mcp_server.tool
    def uppercase(text: str) -> str:
        """Convert a string to uppercase."""
        return text.upper()

  3. Sincronizza le modifiche e ridistribuisci nuovamente l'app.

  4. Ricollega il tuo agente per caricare gli strumenti aggiornati. Chiedigli di chiamare uppercase con hello e conferma che il risultato è HELLO.

Consulta il codice sorgente del modello Starter per l'intero server.

Esporre un'API REST come strumenti MCP

Usa questa opzione quando hai già un'API HTTP, come un'API di ricerca clienti, e vuoi che il tuo agente la richiami. Il template MCP Server (OpenAPI) fornisce strumenti per scoprire e chiamare gli endpoint della tua API.

Passo 1: Prepara l'API

Il modello ha bisogno di due cose:

  • Una descrizione dell'API: Salva la specifica OpenAPI 3.x della tua API come spec.json e caricala su un volume. Mettila alla radice del volume, fuori da qualsiasi sottocartella. Vedi la specifica di esempio.
  • Una connessione HTTP:Crea una connessione che memorizzi le credenziali di autenticazione della tua API, oppure usa una già esistente. Copia il nome della connessione. Crearne uno richiede CREATE CONNECTION.

Passaggio 2: Creare l'app

  1. In Unity Gateway, seleziona MCP, clicca su + MCP e scegli Crea un nuovo server MCP.
  2. Nella pagina di creazione delle appli, sotto Installa da un template, seleziona Agenti, poi MCP Server (OpenAPI).
  3. Per la risorsa uc-volume , seleziona il volume contenente spec.json. Questo dà all'app accesso alla descrizione della tua API.
  4. Continua nelle impostazioni di compute e autorizzazione. Nomina l'app mcp-my-api e clicca su Crea app.

Passo 3: Imposta la connessione API

L'app ha bisogno del nome della connessione HTTP per autenticare le richieste alla tua API.

  1. Nella pagina Panoramica dell'app, fai clic su Modifica nel tuo IDE per copiare il codice sorgente sul tuo computer e impostare la sincronizzazione con lo spazio di lavoro.

  2. app.yaml aperti. Nella env sezione, trova UC_CONNECTION_NAME e imposta il suo valore al nome della tua connessione:

    - name: UC_CONNECTION_NAME
  value: my_api_connection

    Sostituisci my_api_connection con il nome della tua connessione. Lascia invariate le altre impostazioni del template.

  3. Sincronizza il file aggiornato, poi esegui nuovamente il deploy dell'app. Attendi che la distribuzione sia completata in Overview.

Passo 4: Fai la prima chiamata

Ogni chiamante ha bisogno di USE CONNECTION sulla connessione HTTP. Se utilizza OAuth per utente, accedi al provider quando richiesto.

  1. Copia l'URL dell'app da Overview, aggiungi /mcp, e collega il tuo agente.
  2. Chiedi al tuo agente di chiamare list_api_endpoints. Controlla che il risultato includa gli endpoint nella tua specifica.
  3. Chiedi all'agente di chiamare un endpoint di sola lettura e confermare che restituisce dati dalla tua API.

Consulta la fonte del modello OpenAPI per i dettagli della configurazione.

Esempio di specifica OpenAPI

Questa specifica descrive GET /widgets. Sostituisci l'URL e le operazioni con i valori della tua API:

{
  "openapi": "3.1.0",
  "info": { "title": "Example API", "version": "1.0.0" },
  "servers": [{ "url": "https://api.example.com" }],
  "paths": {
    "/widgets": {
      "get": {
        "summary": "List widgets",
        "responses": { "200": { "description": "A list of widgets" } }
      }
    }
  }
}

Distribuire un server MCP esistente

Ospita il tuo server MCP esistente su Databricks Apps.

Passo 1: Prepara il tuo server

La tua cartella sorgente ha bisogno di:

  • Server HTTP: Configura HTTP Streamable. In ascolto su 0.0.0.0 e sulla porta DATABRICKS_APP_PORT (predefinito 8000). Annota il tuo percorso MCP, come /mcp.

  • Dipendenze: Includere il file di dipendenza appropriato, come requirements.txt per Python o package.json per Node.js.

  • Un comando di avvio: Aggiungi app.yaml con il comando che avvia il tuo server. Per un punto di ingresso Python chiamato server.py, si utilizza:

    command: ['python', 'server.py']

Passo 2: Distribuisci e connettiti

  1. In Unity Gateway, seleziona MCP, fai clic su + MCP e scegli Crea un nuovo server MCP.
  2. Nella pagina di creazione delle app, scegli Crea un'app personalizzata. Chiamalo con il mcp- prefisso e completa la configurazione dell'app.
  3. Nella pagina Panoramica dell'app, fai clic su Modifica nel tuo IDE per sincronizzare la cartella sorgente con lo spazio di lavoro.
  4. Clicca su Deploy, seleziona la cartella dello spazio di lavoro, poi clicca su Seleziona e Deploy. Attendere il completamento della distribuzione. Vedi le istruzioni per la distribuzione.
  5. Copia l'URL dell'app e aggiungi il tuo percorso MCP all'URL. Connetti il tuo agente con quell'URL e chiama uno degli strumenti del tuo server per controllare la connessione.

Connetti il tuo agente

Usa l'URL MCP per il percorso che hai scelto. Per i template Starter e OpenAPI, aggiungi /mcp all'URL dell'app. Per un server esistente, usa il percorso MCP configurato nel tuo server.

Scegli la guida alla configurazione del tuo agente:

Gli utenti devono avere CAN USE nell'app. Vedi Autorizzazioni app.

Prezzi e monitoraggio

Le app utilizzano Databricks Apps pricing. Per i log di deploy e i log delle richieste, vedi Logging e monitoraggio per Databricks Apps.

  • Ultimo aggiornamento: