# Server MCP di ExplorerHub > Consulta gli otto quadri di competenze pubblicati su ExplorerHub da Claude Code, Cursor, VS Code, Windsurf o dai tuoi script tramite Model Context Protocol. Accesso con chiave API gratuita, attribuzione delle fonti in ogni risposta. Indirizzo del server: `https://explorerhub.eu/api/mcp` **Il server MCP non è ancora attivo: il lancio è previsto entro il 30 settembre 2026. Fino ad allora l'indirizzo risponde 503 con il codice «disabled» e la creazione di chiavi non è disponibile. Questa pagina resta come documentazione.** ## Che cos'è Model Context Protocol (MCP) è lo standard aperto con cui gli assistenti basati su modelli linguistici si collegano a fonti di dati esterne. Il server MCP di ExplorerHub espone in sola lettura la struttura, i descrittori, i livelli e i glossari di DigComp, DigCompEdu, GreenComp, LifeComp, FinComp, DigCompConsumers, AILit ed EntreComp, negli stessi dati e nelle stesse quattro lingue del sito. Il server è un prodotto di IDCERT S.r.l. Società Benefit e risponde su explorerhub.eu. ## Gli strumenti - `explorerhub_list_frameworks`: Elenca i quadri pubblicati con identificativo, editore, anno, lingue, conteggi e licenza. - `explorerhub_get_framework`: Restituisce la struttura di un quadro: aree, competenze, livelli e, dove il quadro è diviso per pubblico, i segmenti disponibili. - `explorerhub_get_node`: Restituisce un'area o una competenza con tutti i suoi descrittori, raggruppati per livello o per dimensione. - `explorerhub_get_levels`: Restituisce i livelli di padronanza di un quadro, con descrizione e mappature EQF/CEFR dove il documento le dà. - `explorerhub_get_glossary`: Restituisce il glossario di un quadro, filtrabile e paginato. - `explorerhub_search`: Cerca testo o un codice del documento in un quadro o in tutti, con risultati ordinati e link alla pagina. Accetta limit e offset per scorrere i risultati e audience per i quadri con più pubblici; dichiara se l'elenco è troncato e da dove riprendere. ## Come ottenere la chiave 1. Crea un account ExplorerHub, o accedi se ne hai già uno. 2. Nell'area account apri la sezione «Accesso MCP». 3. Dai un nome alla chiave (per esempio il client che la userà) e accetta i termini del servizio MCP: senza l'accettazione la chiave non si crea. 4. Premi «Crea chiave» e copiala subito: viene mostrata una volta sola e non è recuperabile. Se la perdi, revocala e creane un'altra. 5. Passa la chiave al tuo client MCP nell'intestazione Authorization come Bearer token, come negli esempi qui sotto. Le chiavi cominciano con ehk_ e sono lunghe 47 caratteri. Sul server ne è conservata solo l'impronta crittografica: nessuno, nemmeno IDCERT, può rileggere una chiave già creata. Puoi avere al massimo 5 chiavi attive per account; le chiavi revocate non contano. ### Revoca Nell'area account, accanto a ogni chiave, «Revoca» la disattiva subito e in modo definitivo: i client che la usano ricevono 401 dalla chiamata successiva. Revoca una chiave se l'hai esposta, se il dispositivo che la usava non è più tuo o se non ti serve più, e creane una nuova quando ti serve. ## Esempi di configurazione Esporta la chiave in una variabile d'ambiente, come nel primo esempio, e lasciala lì. I file di configurazione del progetto — .mcp.json, .cursor/mcp.json, .vscode/mcp.json — finiscono nel repository: per questo gli esempi riferiscono la variabile, o un input dell'editor, e non la chiave. Non incollare mai la chiave in un file committato e non condividerla. ### Variabile d'ambiente (shell) ```bash export EXPLORERHUB_API_KEY=ehk_YOUR_KEY_HERE ``` ### Claude Code (riga di comando) ```bash claude mcp add --transport http explorerhub https://explorerhub.eu/api/mcp \ --header "Authorization: Bearer ehk_YOUR_KEY_HERE" ``` ### Claude Code (file .mcp.json) ```json { "mcpServers": { "explorerhub": { "type": "http", "url": "https://explorerhub.eu/api/mcp", "headers": { "Authorization": "Bearer ${EXPLORERHUB_API_KEY}" } } } } ``` ### Cursor (mcp.json) — `.cursor/mcp.json` ```json { "mcpServers": { "explorerhub": { "url": "https://explorerhub.eu/api/mcp", "headers": { "Authorization": "Bearer ${env:EXPLORERHUB_API_KEY}" } } } } ``` ### VS Code e GitHub Copilot (.vscode/mcp.json) ```json { "inputs": [ { "type": "promptString", "id": "explorerhub-key", "description": "ExplorerHub MCP API key", "password": true } ], "servers": { "explorerhub": { "type": "http", "url": "https://explorerhub.eu/api/mcp", "headers": { "Authorization": "Bearer ${input:explorerhub-key}" } } } } ``` ### Windsurf (mcp_config.json) — `~/.codeium/windsurf/mcp_config.json` ```json { "mcpServers": { "explorerhub": { "serverUrl": "https://explorerhub.eu/api/mcp", "headers": { "Authorization": "Bearer ${env:EXPLORERHUB_API_KEY}" } } } } ``` ### Claude Desktop tramite mcp-remote (claude_desktop_config.json) ```json { "mcpServers": { "explorerhub": { "command": "npx", "args": [ "mcp-remote", "https://explorerhub.eu/api/mcp", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer ehk_YOUR_KEY_HERE" } } } } ``` L'app Claude Desktop non accetta un'intestazione statica nei propri connettori, ma si collega tramite mcp-remote, un ponte open source di terzi (pacchetto npm, licenza MIT) che gira sul tuo computer, parla con l'app e passa la chiave al server: l'esempio qui sopra è quello del suo README, e la chiave resta nel file di configurazione locale dell'app, che non finisce in nessun repository. I connettori di claude.ai e di ChatGPT richiedono OAuth e al momento non sono supportati. Il server risponde a qualunque client MCP che usi il trasporto Streamable HTTP e invii l'intestazione Authorization. ## Livelli e limiti - **Gratuito**: Incluso con l'account ExplorerHub, per l'uso interattivo con un assistente: 60 chiamate al minuto per chiave e 10.000 chiamate al mese per account. - **Pro**: Per integrazioni ed estrazioni: 600 chiamate al minuto per chiave e 500.000 chiamate al mese per account. Abbonamento mensile o annuale; l'attivazione online non è ancora disponibile: scrivi a support@idcert.io. ### Cosa succede al limite Il limite si misura al minuto e per chiave; senza una chiave valida vale per indirizzo IP e si consuma solo sui tentativi falliti. Oltre il limite il server risponde 429 con un corpo JSON che porta error «rate_limited», scope (key oppure ip), limit e retryAfter, e con l'intestazione Retry-After in secondi. Le intestazioni X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (secondi dall'epoca Unix) accompagnano ogni risposta autenticata, così il client può rallentare prima di essere rifiutato. A ogni account si applica inoltre una quota mensile su tutte le sue chiavi: 10.000 chiamate al mese di calendario (UTC) sul livello gratuito, 500.000 su Pro. Esaurita la quota il server risponde 429 con scope month e un Retry-After che arriva al primo giorno del mese successivo; le intestazioni X-RateLimit-Monthly-Limit, X-RateLimit-Monthly-Remaining e X-RateLimit-Monthly-Reset accompagnano ogni risposta autenticata accanto a quelle del minuto. Una richiesta rifiutata per il minuto non consuma la quota del mese. ## Codici di risposta Ogni risposta porta Cache-Control: no-store. Il server accetta solo POST, che è il trasporto Streamable HTTP del protocollo MCP. | Stato | Corpo | Intestazioni | Significato | |---|---|---|---| | 200 | `JSON-RPC (MCP)` | `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-RateLimit-Monthly-Limit`, `X-RateLimit-Monthly-Remaining`, `X-RateLimit-Monthly-Reset`, `Cache-Control: no-store` | Richiesta autenticata servita. Le intestazioni X-RateLimit dicono quanto resta del limite del minuto. | | 401 | `{"error":"unauthorized","message":"…","docs":"https://explorerhub.eu/en/mcp"}` | `WWW-Authenticate: Bearer realm="ExplorerHub MCP"` | Chiave assente, malformata, sconosciuta o revocata: le quattro condizioni ricevono la stessa risposta, di proposito. Il campo docs rimanda a questa pagina. | | 405 | `—` | `Allow: POST` | Metodo diverso da POST. La risposta arriva prima dell'autenticazione e non consuma nessun limite. | | 429 | `{"error":"rate_limited","scope":"key\|ip\|month","limit":60,"retryAfter":60}` | `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` | Limite superato: del minuto, per chiave (scope key) o per indirizzo IP senza chiave valida (scope ip), oppure della quota mensile dell'account (scope month). Riprova dopo i secondi indicati in Retry-After. | | 503 | `{"error":"disabled"}` | `Retry-After: 300` | Servizio sospeso dall'amministratore. Riprova dopo i secondi indicati in Retry-After. | | 503 | `{"error":"unavailable"}` | `Retry-After: 30` | Il database non risponde. Riprova dopo i secondi indicati in Retry-After; il tentativo non consuma il limite per IP. | ## La forma delle risposte Ogni risposta di un tool porta, oltre ai dati richiesti, due blocchi distinti. attribution dice di chi è il testo del quadro e sotto quale titolo si riusa: licenza o riga di diritti, citazione, provenienza della traduzione nella lingua chiesta. service dice chi ha reso il servizio. Sui tool che leggono un quadro attribution è un oggetto; in explorerhub_list_frameworks e nella ricerca su tutti i quadri è un array con un elemento per quadro. I due blocchi non si fondono, perché IDCERT non è titolare del testo dei quadri. ```json { "framework": { "id": "digcomp", "name": "DigComp", "version": "3.0" }, "attribution": { "framework": { "id": "digcomp", "name": "DigComp", "version": "3.0", "producer": "JRC", "publisher": "Joint Research Centre, European Commission", "year": 2025, "citation": "Cosgrove, J., Cachia, R., DigComp 3.0: European Digital Competence Framework – Fifth Edition, EUR 40491, Publications Office of the European Union, Luxembourg, 2025, ISBN 978-92-68-32677-0, doi:10.2760/0001149, JRC144121.", "doi": "10.2760/0001149", "sourceUrl": "https://publications.jrc.ec.europa.eu/repository/handle/JRC144121" }, "license": { "url": "https://creativecommons.org/licenses/by/4.0/", "requiresAttribution": true }, "rightsStatement": null, "translation": { "locale": "it", "provenance": [ "official", "idcert" ], "notice": "The it text is an edition edited by IDCERT, not an official edition (in part; the rest is the publisher's own edition). The European Commission is not responsible for this translation." }, "attributionPage": "https://explorerhub.eu/en/legal/attribution" }, "service": { "name": "ExplorerHub MCP", "provider": "IDCERT S.r.l. Società Benefit", "url": "https://explorerhub.eu", "endpoint": "https://explorerhub.eu/api/mcp", "termsOfService": "https://explorerhub.eu/en/legal/mcp-terms", "notice": "Data obtained through ExplorerHub MCP (https://explorerhub.eu/api/mcp), a service of IDCERT S.r.l. Società Benefit. Framework content is reproduced from the official publication named in `attribution`, under that publication's own licence or rights statement: when you redistribute it, credit its publisher as that licence requires. Use of this service is governed by the ExplorerHub MCP terms of service (https://explorerhub.eu/en/legal/mcp-terms), which ask you to state that the data was obtained through ExplorerHub by IDCERT S.r.l. Società Benefit, in addition to the publisher's attribution." } } ``` _Esempio generato dalle stesse funzioni del server, per DigComp nella lingua di questa pagina; i campi propri del tool (albero, descrittori, risultati) sono omessi._ ## Come citare Chi riutilizza i dati dichiara la fonte del testo come la licenza del quadro richiede e, accanto, il servizio con cui li ha ottenuti — mai al posto dell'editore. Una formula pronta da copiare, per DigComp: > Cosgrove, J., Cachia, R., DigComp 3.0: European Digital Competence Framework – Fifth Edition, EUR 40491, Publications Office of the European Union, Luxembourg, 2025, ISBN 978-92-68-32677-0, doi:10.2760/0001149, JRC144121. Dati ottenuti tramite ExplorerHub MCP, servizio di IDCERT S.r.l. Società Benefit (https://explorerhub.eu/api/mcp). ## Licenze e attribuzione I testi dei quadri sono pubblicazioni della Commissione europea, del Centro comune di ricerca (JRC) e dell'OCSE, riprodotti alle condizioni delle rispettive licenze Creative Commons o autorizzazioni di riuso. Ogni risposta del server porta la citazione, la licenza e la provenienza della traduzione: chi ridistribuisce quel testo deve conservarle. L'uso del servizio è regolato dai termini MCP, che chiedono di dichiarare che i dati sono stati ottenuti tramite ExplorerHub di IDCERT S.r.l. Società Benefit, accanto all'attribuzione all'editore. Le edizioni tradotte a cura di IDCERT sono dichiarate come tali e non sono edizioni ufficiali. ExplorerHub e IDCERT non sono affiliati alla Commissione europea, al JRC o all'OCSE. - [Attribuzione delle fonti](https://explorerhub.eu/it/legal/attribution) - [Termini del servizio MCP](https://explorerhub.eu/it/legal/mcp-terms)