MCP — Model Context Protocol

Cos'è MCP

Model Context Protocol è uno standard aperto di Anthropic per la connessione di applicazioni LLM a fonti di dati e strumenti esterni. Il client AI (Claude Desktop, app personalizzata) legge l'elenco degli strumenti disponibili dal server MCP e decide autonomamente quale richiamare in base alla conversazione con l'utente.

Il server MCP di Veritra funziona come transport HTTP — nessun processo locale, un unico endpoint POST che accetta richieste JSON-RPC.

Endpoint e autenticazione

Utilizza la management API key (mrw_…) nell'header Authorization. L'header X-MRW-Client: mcp segnala che la chiamata proviene da un client MCP (utilizzato internamente per il tracciamento dell'audience e la verifica dei diritti di accesso).

Authorization: Bearer mrw_7fa7785c3d6e…
X-MRW-Client: mcp
Content-Type: application/json

La chiave si trova nella dashboard dopo l'onboarding. La stessa chiave funziona sia per REST sia per MCP — nessuna configurazione separata.

Envelope JSON-RPC

Ogni richiesta e risposta segue la specifica JSON-RPC 2.0. tools/list per la discovery, tools/call per l'invocazione dello strumento.

Richiesta

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tenders_search",
    "arguments": { "qText": "rekonstrukce mostu", "limit": 10 }
  }
}

Risposta

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "{ … JSON payload … }" }]
  }
}

In caso di errore, nella risposta è presente un oggetto error al posto di result:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32602, "message": "Invalid params: qText is required" }
}

Discovery (tools/list)

Il client legge l'elenco degli strumenti disponibili — il server restituisce definizioni di strumenti conformi allo standard MCP, incluso lo schema JSON per i parametri.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

La risposta contiene l'array tools[] con oggetti { name, description, inputSchema }. Il client AI utilizza inputSchema per la validazione degli argomenti.

Catalogo degli strumenti

Attualmente 9 strumenti in 4 categorie: tenders (search/detail/filters), leads (filters), accounts, subscriptions, meta.

tenders_search

Ricerca live di gare d'appalto su tutti i portali. Restituisce i top N bandi con dettaglio (titolo, valore, scadenza, stazione appaltante, …).

tenders_get_detail

Dettaglio di una singola gara, inclusi documenti e flag di preferenza.

tenders_list_industries

Restituisce l'elenco dei tag di settore (con_buildings, it_development, …) per il filtraggio — l'agente può mostrare all'utente un menu leggibile anziché dover digitare gli ID.

tenders_list_regions

Restituisce l'elenco delle regioni NUTS per un determinato paese (CZ predefinito).

leads_list_filters

Elenco dei filtri LEADS salvati dall'utente.

I filtri creati tramite MCP / REST vengono utilizzati anche nelle e-mail, nelle notifiche push e nei webhook — l'agente può configurarli e l'utente li riceve attraverso i canali standard.

leads_create_filter

Crea un nuovo filtro LEADS. A ogni nuova corrispondenza con una gara viene attivato un webhook e un digest via e-mail.

account_create_webhook

Registra un endpoint webhook HTTPS per la ricezione di eventi (leads.match.created ecc.). Restituisce l'ID endpoint e il secret per la verifica HMAC. Il secret viene mostrato UNA SOLA VOLTA — salvarlo nella propria variabile ENV.

Massimo 5 endpoint per account. Per la rotazione del secret utilizzare /api/v2/account/webhooks/:id/rotate-secret.

subscriptions_list_plans

Catalogo pubblico di servizi e prezzi (LEADS, PRICING, PROCUREMENT). Senza autenticazione.

meta_list_services

Stato di tutti i servizi di Veritra (uptime, flag di deprecazione).

Esempio curl

Ricerca dei top 5 appalti edilizi superiori a 1M CZK a Praga:

curl -X POST https://veritra.io/api/mcp \
  -H "Authorization: Bearer mrw_…" \
  -H "X-MRW-Client: mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "tenders_search",
      "arguments": {
        "industryTags": ["con_buildings"],
        "regions": ["CZ010"],
        "minValue": 1000000,
        "limit": 5
      }
    }
  }'

Configurazione in Claude Desktop

Aggiungere a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o equivalente:

{
  "mcpServers": {
    "veritra": {
      "url": "https://veritra.io/api/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer mrw_…",
        "X-MRW-Client": "mcp"
      }
    }
  }
}

Dopo il riavvio di Claude Desktop, nell'interfaccia sarà visibile l'icona del server MCP connesso. Aprire una conversazione e chiedere, ad esempio, 'Quali sono le attuali gare d'appalto edilizie a Praga superiori a un milione?' — Claude chiamerà automaticamente tenders_search.

Altri client MCP

Il server MCP è in esecuzione come trasporto HTTP — compatibile con qualsiasi client che supporti JSON-RPC 2.0 via HTTP. Di seguito alcuni esempi per i casi più comuni.

Cursor / Continue / Cline / Zed

Cursor IDE dispone di supporto MCP integrato. Modificare ~/.cursor/mcp.json:

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "veritra": {
      "url": "https://veritra.io/api/mcp",
      "headers": {
        "Authorization": "Bearer mrw_mgmt_…",
        "X-MRW-Client": "mcp"
      }
    }
  }
}

Continue.dev

Estensione VS Code open-source. Aggiungere a config.json:

// ~/.continue/config.json (snippet)
"mcpServers": [
  {
    "name": "veritra",
    "transport": { "type": "http", "url": "https://veritra.io/api/mcp" },
    "requestOptions": {
      "headers": {
        "Authorization": "Bearer mrw_mgmt_…",
        "X-MRW-Client": "mcp"
      }
    }
  }
]

Client HTTP MCP generico / plugin ChatGPT / LLM personalizzato

Se il client non dispone di supporto MCP nativo, comunicare direttamente con l'API tramite JSON-RPC 2.0. Le intestazioni Authorization e X-MRW-Client identificano il proprio account. La discovery (tools/list) è la prima chiamata da effettuare.

POST https://veritra.io/api/mcp HTTP/1.1
Authorization: Bearer mrw_mgmt_<your_key>
X-MRW-Client: mcp
Content-Type: application/json

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

Limiti di frequenza (rate limit)

Le chiamate MCP rientrano negli stessi limiti dell'API di gestione (60/min in lettura, 10/min in scrittura, 5000/giorno). In caso di superamento viene restituito HTTP 429 (codice errore JSON-RPC -32000).