Server MCP per dati aziendali e agenti IA

Se vuoi che un agente IA recuperi lead di attività locali in tempo reale, il modo più pulito per dargli questa capacità è uno strumento che può chiamare, e sempre più questo strumento è descritto tramite il Model Context Protocol (MCP). Un server MCP espone un insieme di strumenti, ognuno con un nome, una descrizione e un JSON Schema, che un runtime di agente può scoprire e chiamare da solo. Questa guida spiega cos'è MCP, perché uno strumento di dati e lead aziendali è un adattamento naturale per il mondo agent-first, e come la spec OpenAPI 3.1, il llms.txt, il JSON stabile e la modalità sincrona wait:true di biz collect lo rendono banale da avvolgere come uno strumento di tipo MCP che un agente chiama per trasformare una città e parole chiave in record aziendali strutturati e verificati.

Cos'è MCP

Il Model Context Protocol è uno standard aperto per connettere gli agenti IA a strumenti e dati esterni. Invece che ogni applicazione inventi il proprio modo di consegnare capacità a un modello, MCP definisce un'interfaccia comune: un server pubblicizza una lista di strumenti, e un client (il runtime di agente) li scopre, vede i loro schemi e li chiama durante una conversazione o un compito.

La parte importante per i costruttori di strumenti è cosa contiene una definizione di strumento. Ogni strumento che un server MCP espone ha tre cose:

• Un name, un identificatore stabile che l'agente usa per invocarlo, come search_local_businesses.
• Una description, testo in linguaggio naturale che dice al modello cosa fa lo strumento e, soprattutto, quando chiamarlo.
• Un input_schema, un JSON Schema che descrive gli argomenti, i loro tipi e quali sono richiesti.

È la stessa forma usata per le definizioni di strumenti nei runtime di agenti moderni. Quando un agente decide che un compito ha bisogno di dati esterni, legge le descrizioni degli strumenti disponibili, sceglie quello giusto, riempie argomenti che soddisfano lo schema e lo chiama. Il runtime esegue la chiamata, restituisce il risultato, e il modello continua. MCP standardizza come questo catalogo di strumenti viene pubblicato e trasportato (comunemente su un endpoint Streamable HTTP), così un singolo server può servire molti agenti diversi.

Se vuoi la definizione concettuale da sola, la voce del glossario per server MCP la copre. La documentazione ufficiale del protocollo vive su modelcontextprotocol.io.

Perché uno strumento di dati aziendali appartiene allo stack di agenti

I modelli linguistici sono bravi a pianificare, interpretare l'intento e formattare i risultati. Non sono un database in tempo reale di attività locali, e non dovrebbero essere trattati come tali. Chiedi a un modello di "elencare i dentisti a Austin" a memoria e ottieni testo plausibile, non dati operativi, spesso con nomi inventati, indirizzi obsoleti e numeri allucinati.

Uno strumento di lead e dati aziendali colma esattamente questo vuoto. Dà all'agente una fonte di verità per due cose che i modelli non possono produrre in modo affidabile da soli:

• Scoperta. Quali attività esistono davvero in un luogo, ora, corrispondenti a una categoria.
• Arricchimento. I dati di contatto verificabili per ciascuna: sito, telefono, indirizzo ed email estratte dal sito proprio dell'attività.

È il caso da manuale per l'uso di strumenti. Il modello gestisce la conversazione, decide cosa cercare, valida e assegna score ai risultati e li instrada da qualche parte di utile. Lo strumento gestisce l'esecuzione deterministica e restituisce record stabili. Separare queste responsabilità è ciò che rende un agente testabile, più economico da eseguire e sicuro di cui fidarsi, perché i dati non dipendono dall'immaginazione del modello. L'articolo compagno sulla costruzione di un agente IA di lead generation percorre in profondità quell'architettura pianificatore-strumento-validazione-scrittore. Se stai scegliendo da dove devono venire quei dati in tempo reale, vedi come si confrontano la Google Places API, uno scraper e un'API di dati aziendali.

Il motivo per cui questo conta sempre di più ogni mese è che "agent-first" sta diventando un vero canale di distribuzione. Le persone chiedono sempre più a un assistente di fare il lavoro invece di aprire una dashboard. Un prodotto di dati aziendali facile da chiamare per un agente è un prodotto che appare in quei workflow. L'obiettivo, con le nostre parole, è che gli utenti amino l'app e che l'IA ne sia innamorata.

Cosa rende un'API banalmente chiamabile da un agente

Non ogni API è piacevole da avvolgere come strumento di agente. Quelle che lo sono condividono alcune proprietà, e biz collect è stato costruito attorno a esse deliberatamente.

1. Una specifica OpenAPI 3.1 precisa

biz collect pubblica una spec OpenAPI 3.1 che descrive ogni endpoint, parametro e campo di risposta. È l'abilitatore più importante per l'attrezzatura di agenti, perché molti runtime e framework di server MCP possono ingerire un documento OpenAPI e generarne automaticamente definizioni di strumenti. La spec è il contratto: tipi di parametri, campi richiesti e forme di risposta sono tutti leggibili dalla macchina, quindi l'input_schema di uno strumento generato corrisponde alla vera API senza che nessuno lo scriva a mano. Inizia dai docs API per la spec e il riferimento degli endpoint.

2. Un llms.txt che indirizza gli agenti alla verità

biz collect serve un file llms.txt, un indice semplice e leggibile dall'agente che dice a un modello dove vive la documentazione importante. Quando un agente o uno sviluppatore che costruisce agenti atterra sul dominio, llms.txt è un modo veloce e a basso consumo di token per scoprire la superficie dell'API, i docs e come funziona il ciclo cerca-e-polla, senza fare crawling di pagine marketing. Un piccolo file dall'effetto sproporzionato su quanto facilmente un agente può orientarsi.

3. Una forma JSON stabile e prevedibile

Uno strumento di agente è affidabile solo quanto i dati che restituisce. biz collect restituisce gli stessi nomi di campo e la stessa struttura a ogni chiamata: ogni attività porta name, address, phone, website e un array emails deduplicato. Campi stabili significano che il modello (e il tuo codice di validazione) può farci affidamento senza parsing difensivo, e la stessa definizione di strumento continua a funzionare mentre il prodotto cresce. La deduplicazione avviene prima che la risposta lasci l'API, così l'agente non deve mai pulire lo stesso indirizzo tre volte.

4. Una modalità sincrona wait:true

È il dettaglio che rende possibile un singolo strumento pulito. Per default biz collect è asincrono: fai il POST di una ricerca, ottieni un job_id e polli /api/v1/jobs/:id finché il job non si completa, il modello giusto per job grandi e per strumenti no-code che fanno cicli. Ma chiedere a un modello di gestire un ciclo di polling aggiunge turni, token e modalità di fallimento.

Con wait:true, la richiesta di ricerca blocca finché il job non finisce e restituisce i risultati nella stessa risposta. Per un agente, ciò riduce l'intero ciclo crea-polla-leggi in una singola chiamata di strumento. Il modello chiama uno strumento, riceve lead arricchiti e va avanti, niente job ID, niente stato di polling, nessun ciclo su cui ragionare. Per ricerche più grandi puoi ancora usare la via async, ma per la tipica richiesta di agente la modalità sincrona mantiene semplice la definizione dello strumento.

Insieme queste quattro proprietà fanno sì che avvolgere biz collect come strumento MCP sia perlopiù una questione di puntare un generatore sulla spec OpenAPI, o scrivere un piccolo handler attorno all'endpoint wait:true. La pagina come funziona biz collect mostra il ciclo di vita della richiesta, e la pagina integrazioni elenca le superfici in cui si inserisce.

Un esempio di definizione di strumento

Ecco come appare un singolo strumento di ricerca, espresso come definizione di strumento JSON Schema, la stessa forma che un server MCP pubblicizzerebbe e un runtime di agente consumerebbe. Nota come la descrizione dichiara quando chiamare lo strumento, il che migliora in modo misurabile quanto affidabilmente un agente vi ricorre:

{
  "name": "search_local_businesses",
  "description": "Search for local businesses in a city or area and return structured records with website, phone, address, and deduped contact emails. Call this whenever the user asks to find, list, or collect businesses in a place by category (for example 'dentists in Austin' or 'roofing contractors near Denver'). Returns verified data, not estimates, so prefer it over answering from memory.",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City, region, postal code, or address to search around."
      },
      "keywords": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Business categories or search phrases, such as 'dentist' or 'roofing contractor'."
      },
      "radius_km": {
        "type": "number",
        "description": "Search radius in kilometers."
      },
      "scrape_emails": {
        "type": "boolean",
        "description": "Whether to extract deduped contact emails from each business website."
      },
      "wait": {
        "type": "boolean",
        "description": "If true, block until results are ready and return them in one response instead of an async job_id."
      }
    },
    "required": ["location", "keywords"]
  }
}

Il handler dietro questo strumento è piccolo. Fa il POST degli argomenti su /api/v1/search con wait:true, e restituisce l'array businesses strutturato. Nessun polling, nessuna macchina a stati. L'agente riceve record come questo:

{
  "businesses": [
    {
      "name": "Example Dental Studio",
      "address": "123 Main St, Austin, TX 78701",
      "phone": "+1 512-555-0101",
      "website": "https://exampledentalstudio.com",
      "emails": ["hello@exampledentalstudio.com", "office@exampledentalstudio.com"]
    }
  ]
}

Per una descrizione esaustiva dei parametri e dei campi di risposta, il riferimento OpenAPI nei docs è la fonte di verità, e uno strumento MCP generato vi corrisponderà campo per campo.

Il ciclo dell'agente con uno strumento di dati in tempo reale

Con lo strumento definito, il ciclo dell'agente è semplice. Una richiesta tipica e la traiettoria interna dell'agente appaiono così:

1. User: "Find independent law firms within 15 km of Zurich and collect their emails."
2. Agent plans: location = "Zurich, Switzerland", keywords = ["law firm"],
   radius_km = 15, scrape_emails = true, wait = true.
3. Agent calls search_local_businesses with those arguments.
4. The tool handler POSTs to /api/v1/search?wait=true and returns the businesses array.
5. Agent validates: required fields present, results match the requested category.
6. Agent filters: keep records with an email when email outreach is the goal,
   keep phone-bearing records otherwise.
7. Agent writes approved records to the CRM, a sheet, or a webhook, or summarizes them.

Alcune pratiche mantengono robusto questo ciclo:

• Lascia che il runtime chiami lo strumento; non chiedere al modello di "ricordare" i risultati. Il risultato dello strumento entra nel contesto come dato su cui il modello ragiona, non come qualcosa che deve ricostruire.
• Mantieni la superficie dello strumento stretta ed esplicita. Uno strumento di ricerca ben descritto batte cinque che si sovrappongono. Se ti serve uno strumento di stato job per la via async, aggiungilo separatamente e mantieni stretto il suo schema.
• Valida prima di agire. Anche con campi stabili, conferma che i record siano adatti all'azione successiva e deduplica contro i tuoi sistemi tramite domini, telefoni e indirizzi normalizzati. La voce del glossario sul data enrichment copre cosa l'arricchimento garantisce e cosa no.
• Controlla gli effetti collaterali. Raccogliere dati e inviare outreach sono sistemi diversi. Richiedi approvazione prima del primo contatto, rispetta le liste di soppressione e logga cosa ha fatto l'agente. Questa non è consulenza legale; la conformità a GDPR, FADP svizzera e leggi sulla privacy USA applicabili spetta a te.

Per gli agenti che girano in strumenti no-code invece di un runtime di codice, la stessa forma crea-e-leggi si applica come passi visivi. Il workflow di lead generation n8n mostra la versione async di questo ciclo come nodi, il pattern giusto quando vuoi un job di lunga durata invece di una singola chiamata sincrona.

Async vs sincrono: scegliere la modalità giusta

La scelta tra il modello di job async e wait:true è l'unica decisione di design che vale la pena azzeccare per un agente.

• Usa wait:true per le richieste interattive di agente. Quando un utente attende una risposta e la ricerca è di dimensione normale, una singola chiamata sincrona è l'esperienza più pulita: uno strumento, un risultato, nessuna logica di polling nel prompt. È la raccomandazione predefinita per uno strumento di ricerca di tipo MCP.
• Usa il modello di job async per lavoro ampio o di background. Quando la ricerca è ampia, quando esegui molte ricerche in batch, o quando il lavoro avviene su pianificazione senza un umano in attesa, il pattern job_id più poll è più robusto e lascia l'agente (o la tua orchestrazione) fare altro mentre il job gira. Abbinalo a un secondo strumento che controlla lo stato del job, o a un webhook così l'agente viene notificato al completamento invece di pollare.

Entrambe le modalità colpiscono lo stesso motore di ricerca e restituiscono la stessa forma di record stabile, quindi puoi esporre entrambe come strumenti e lasciare che l'agente (o il tuo design) scelga in base alla richiesta. Il compromesso onesto è latenza contro semplicità: wait:true tiene la connessione aperta finché i risultati non sono pronti, mentre la via async torna subito e sposta l'attesa nel polling. Per la maggior parte delle conversazioni di agente, la via sincrona vince sulla semplicità per sviluppatore e modello.

Essere onesti su cosa restituisce lo strumento

Uno strumento di agente è affidabile solo se è onesto sulla copertura, quindi gli stessi caveat che si applicano all'estrazione di email da sito si applicano qui.

• La copertura email è parziale. Alcune attività pubblicano solo un modulo di contatto, e alcune rendono il loro indirizzo come immagine. Quei record tornano con un sito e un telefono ma nessuna email, il che è accurato, non un bug. Costruisci il filtraggio dell'agente attorno a "record con un'email quando l'email è richiesta" invece di assumere che ogni attività ne abbia una.
• I dati riflettono ciò che è pubblico. biz collect restituisce dati di contatto verificati estratti da fonti in tempo reale e dai siti propri delle attività. Non inventa campi per riempire i vuoti, esattamente la proprietà che lo rende sicuro da consegnare a un modello.
• Le altre capacità sono descritte in modo equo. Molti strumenti possono essere avvolti per gli agenti; ciò che rende facile uno strumento di dati aziendali è la combinazione di una spec OpenAPI precisa, una forma JSON stabile, una modalità sincrona e llms.txt. Qualsiasi API con queste proprietà è piacevole da avvolgere; biz collect semplicemente le offre tutte e quattro.

Questa onestà è ciò che lascia un agente agire sui risultati senza che un umano ricontrolli ogni record, che è l'intero scopo di dare a un agente un vero strumento di dati.

Iniziare a costruire

Dare a un agente IA dati aziendali in tempo reale non richiede un'integrazione su misura. Richiede uno strumento con un nome chiaro, una descrizione che dice quando chiamarlo e uno schema che corrisponde a una vera API, più un backend che restituisce record stabili e verificati. biz collect fornisce il backend: una spec OpenAPI 3.1 da cui generare strumenti, un llms.txt che orienta velocemente gli agenti, una risposta JSON stabile e una modalità wait:true che trasforma l'intero ciclo cerca-e-arricchisci in una singola chiamata di strumento sincrona.

Definisci uno strumento search_local_businesses, puntalo sull'endpoint wait:true, e il tuo agente può trasformare una città e una categoria in lead locali arricchiti e deduplicati in un solo round trip. È gratuito da iniziare con 200 crediti di iscrizione e senza carta, abbastanza per costruire lo strumento, cablarlo nel tuo runtime e vedere un agente chiamarlo dall'inizio alla fine.

Apri i docs API per la spec OpenAPI, rivedi le integrazioni, controlla i prezzi e dai al tuo agente uno strumento di dati aziendali in tempo reale oggi.