NACEBridge API & MCP

NACEBridge mappa EU NACE Rev 2.1 fino alle sottoclassi nazionali a 5 cifre usate da 27 stati membri UE, Regno Unito e Svizzera (CAE-Rev4 PT, NAF FR, WZ DE, SBI NL, …). Le quattro utility web sono disponibili anche in modo programmatico:

• search — ricerca per parola chiave globale + locale
• decode — espandere un codice nazionale nella sua gerarchia EU completa
• cousins — sottoclassi equivalenti transfrontaliere
• grid — pivot multi-paese per una divisione NACE

Ogni richiesta a /api/v1/* porta un header X-API-Key. Accedi e genera le chiavi nel tuo pannello chiavi API. Le chiavi sono hashed a riposo — non memorizziamo mai il testo in chiaro.

X-API-Key: nb_live_XXXXXXXXXXXXXXXXXXXXXXXX

L'endpoint MCP usa esattamente lo stesso header, esattamente gli stessi limiti per tier e esattamente lo stesso registro delle richieste del gateway REST — l'unica differenza è la URL (/mcp invece di /api/v1/…) e l'envelope JSON-RPC. Il traffico web anonimo è ammesso per le utility UI ma è soft-limitato da un contatore di strike per IP (vedi Limiti di richieste).

Picchi oltre il tetto della finestra restituiscono HTTP 429 con Retry-After.

Cinque risorse sotto https://nacebridge.dev/api/v1/*. Ogni endpoint accetta GET con query params o POST con body JSON. Le risposte sono { ok, tier, data } con header X-RateLimit-* allegati.

# Decode a Portuguese CAE-Rev4 code
curl -s "https://nacebridge.dev/api/v1/decode?country_iso=PT&code=62010" \
  -H "X-API-Key: $NACEBRIDGE_API_KEY"

# Or POST JSON
curl -s "https://nacebridge.dev/api/v1/cousins" \
  -H "X-API-Key: $NACEBRIDGE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"country_iso":"DE","code":"62.01.0"}'

NACEBridge parla la specifica MCP Streamable HTTP transport . Punta qualsiasi client MCP a:

https://nacebridge.dev/mcp

POST JSON-RPC 2.0 con entrambi i content-type in Accept:

POST /mcp HTTP/1.1
Content-Type: application/json
Accept: application/json, text/event-stream

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

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "nacebridge": {
      "url": "https://nacebridge.dev/mcp",
      "headers": { "X-API-Key": "nb_live_..." }
    }
  }
}

ChatGPT (Plus / Pro / Team): aggiungere come Connector personalizzato con la stessa URL — gli strumenti search e fetch sono esposti per Deep Research.

Cursor: aggiungere a ~/.cursor/mcp.json con la stessa URL.

Istruzioni drop-in che insegnano al tuo assistente AI quando e come chiamare NACEBridge. Scarica, installa nell'assistente di tua scelta, e la prossima volta che l'utente incolla un codice NACE / CAE / NAF / WZ / SBI l'assistente userà il server MCP invece di indovinare.

Tutti e tre referenziano solo le URL pubbliche MCP e REST. Non contengono alcuna chiave API — gli utenti forniscono la propria dal pannello chiavi API.

npm i @nacebridge/sdk

import { NACEBridge } from "@nacebridge/sdk";
const nb = new NACEBridge({ apiKey: process.env.NACEBRIDGE_API_KEY });

const cousins = await nb.cousins({ country_iso: "NL", code: "6201" });
const grid    = await nb.grid({ division: "62", countries: ["PT","FR","DE","NL"] });

Il wrapper open source vive in public-wrappers/mcp/. È un proxy httpx leggero — zero dati locali — così il gateway privato rimane la fonte di verità.

pip install -e ./public-wrappers/mcp

# Then in your MCP client config:
{
  "mcpServers": {
    "nacebridge-local": {
      "command": "python",
      "args": ["-m", "nacebridge_mcp"],
      "env": {
        "NACEBRIDGE_API_KEY": "nb_live_...",
        "NACEBRIDGE_URL": "https://nacebridge.dev"
      }
    }
  }
}

Pubblichiamo una site-map leggibile da macchina in /llms.txt e un indice più ricco in /llms-full.txt perché gli assistenti AI si auto-onboardino. Il blocco Ask-an-AI in homepage apre una chat fresca su ChatGPT, Claude, Gemini, Grok o Perplexity — innescata con un prompt NACEBridge che dice all'assistente di usare il server MCP invece di indovinare.

• 401 — X-API-Key mancante o non valido
• 402 — quota tier esaurita, upgrade richiesto
• 422 — input non ha superato la validazione Zod; la risposta riporta i dettagli per campo
• 429 — limite di richieste raggiunto, rispettare Retry-After
• 5xx — incidente; i retry sono sicuri (tutte le operazioni sono in sola lettura)

Metadati NACE Rev 2.1 © Unione europea, riutilizzati ai sensi della politica di riutilizzo della Commissione. Metadati delle sottoclassi nazionali © rispettivi istituti nazionali di statistica (INE, INSEE, DESTATIS, CBS, …). Le corrispondenze NACEBridge, lo schema normalizzato e i wrapper sono distribuiti da TΣKSOMΛ Holding, Lda., realizzato da TΣKSOMΛ Technologies e alimentato da TΣKSOMΛ | MΛRKET INTΣLLIGENCE.