OData to MCP: collegare servizi OData V2/V4 e SAP Gateway a Claude

Risposta breve: AnythingMCP ha un tipo di connettore OData. Puntalo su un servizio OData V2 o V4, o su un SAP Gateway, e Claude, ChatGPT e Copilot ricevono cinque tool: trovare i servizi, leggere entity set e campi con le loro etichette di business, interrogare righe e leggere un'entità per chiave. Le query vengono verificate su $metadata prima dell'invio, il paging del server viene seguito, e le risposte V2 e V4 tornano come righe semplici. Puoi anche importare il $metadata di un servizio come tool con un nome, un tool list e uno get per ogni entity set.

Perché OData richiede più di un import REST

Un servizio OData descrive sé stesso. Il suo documento $metadata elenca ogni entity set, le sue chiavi, il tipo di ogni campo e, nel caso di SAP, l'etichetta che l'utente vede a schermo, la valuta o l'unità che appartiene a ogni importo, e quali campi sono dimensioni e quali misure. Un import REST generico butta via quasi tutto, e il modello deve indovinare che NetAmount è in TransactionCurrency, o che un servizio analitico va filtrato con un parametro.

Il connettore OData legge $metadata e lo passa al modello. Claude vede che NetAmount ha l'etichetta Net Amount e la sua valuta in TransactionCurrency, e quando sbaglia il nome di un campo il connettore risponde "Unknown field … Did you mean …" invece di girare l'errore al server.

Due modi per averlo

• Il tipo di connettore OData. Scegli OData quando crei un connettore. Attiva SAP Gateway (S/4HANA, ECC, BW) per un sistema SAP: l'URL di base è l'host, es. https://s4.example.com:44300, e i servizi arrivano dal catalogo di SAP. Lascialo disattivato per un singolo servizio OData: l'URL di base è la root del servizio, es. https://services.example.com/odata/v4/Sales.
• Un connettore REST con impostazioni OData. Un connettore REST le cui impostazioni hanno un blocco odata riceve gli stessi tool integrati; i suoi tool restano normali chiamate REST. L'adapter SAP S/4HANA Cloud funziona così.

Entrambi girano sul motore REST, quindi vale ogni metodo di autenticazione REST, così come i retry, la protezione SSRF in uscita e il proxy.

I tool integrati

Ogni connettore OData riceve cinque tool con nome <prefix>_…. Il prefisso è il nome del connettore più _odata, oppure uno che scegli tu.

I tool integrati leggono soltanto e sono marcati in sola lettura per i client MCP.

Configurazione

Passo 1: Avvia AnythingMCP

Per un servizio OData pubblico, AnythingMCP Cloud va benissimo. Per un SAP Gateway o un servizio nella tua rete, installa AnythingMCP self-hosted dove può raggiungere il servizio:

mkdir anythingmcp && cd anythingmcp
curl -fsSLo docker-compose.yml \
  https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d   # → http://localhost:3000

Aggiungi i nomi host interni a SSRF_ALLOWED_HOSTS; di default AnythingMCP rifiuta gli indirizzi privati.

Passo 2: Crea un connettore OData

Crea un nuovo connettore, scegli OData e inserisci l'URL di base. Per provarlo senza un account da nessuna parte, usa il servizio pubblico Northwind: https://services.odata.org/V4/Northwind/Northwind.svc, SAP Gateway disattivato, nessuna autenticazione. Per SAP, attiva SAP Gateway e inserisci il mandante a tre cifre e la lingua.

Passo 3: Imposta l'autenticazione e limita i servizi

Scegli l'autenticazione che il servizio si aspetta: Basic auth con un utente tecnico, OAuth 2.0 (client credentials o authorization code), una API key, un certificato client o un login token. Nelle impostazioni OData del connettore elenca in Allowed services i percorsi dei servizi che il modello può chiamare (* come jolly); gli altri servizi vengono rifiutati.

Passo 4: Testa e importa i tool

Test connection legge il catalogo SAP o il $metadata del servizio. Se vuoi tool con un nome per gli entity set che il modello usa di più, apri Import Tools → OData $metadata, indica il percorso del servizio (SAP) o lascialo vuoto (servizio singolo) e scegli gli entity set. Vedi sotto.

Passo 5: Collega Claude, ChatGPT o Copilot

• Claude: Personalizza → Connettori → Aggiungi connettore personalizzato, incolla l'URL del tuo server MCP. Passo per passo: come aggiungere un connettore personalizzato a Claude.
• ChatGPT: aggiungi lo stesso URL HTTPS pubblico come connettore (app) nelle impostazioni di ChatGPT.
• Claude Code, Cursor, VS Code / Copilot: aggiungi l'URL con un header X-API-Key.

Importare i tool da $metadata

Import Tools → OData $metadata trasforma gli entity set in tool con un nome: <set>_list con filter, select, orderby, top, skip ed expand, e <set>_get con i parametri della chiave. Il documento viene scaricato con le credenziali del connettore; puoi anche incollare un documento $metadata e limitare l'import ad alcuni entity set. Reimportare un servizio aggiorna i suoi tool e ritira solo i tool di quel servizio che sono spariti, mai quelli integrati o quelli di un altro servizio.

Su un connettore OData, i tool HTTP importati o scritti a mano ricevono mandante e lingua SAP, il formato JSON per V2 e risposte appiattite. Le scritture su SAP (POST, PUT, PATCH, DELETE) recuperano prima un token CSRF con i cookie di sessione. Si scrive solo tramite tool che importi o scrivi tu.

SAP Gateway: S/4HANA, ECC e BW

1. Un utente tecnico di tipo System, con password produttiva, nel mandante che vuoi leggere.
2. Un ruolo con S_SERVICE per i servizi che il modello può chiamare e autorizzazioni di business di sola visualizzazione. Per sfogliare il catalogo, anche il servizio di catalogo V2 /IWFND/CATALOGSERVICE e il catalogo V4. SAP controlla queste autorizzazioni a ogni chiamata; sono il vero confine.
3. Servizi attivi in /IWFND/MAINT_SERVICE (V2) e /IWFND/V4_ADMIN (V4).
4. Rete: la porta del Gateway di solito è interna. Installa AnythingMCP self-hosted nella rete o raggiungila via VPN.

La policy API di SAP si aspetta che le integrazioni di terze parti usino API pubblicate (i servizi API_* sul SAP Business Accelerator Hub) o servizi che hai costruito tu; limita Allowed services di conseguenza.

Per S/4HANA on-premise e Private Cloud c'è un adapter pronto, SAP S/4HANA (OData). Imposta tutto questo con il prefisso s4 (s4_list_services, s4_describe_service, s4_describe_entity, s4_query, s4_get_entity) e aggiunge tool pronti per righe di registrazione contabile, documenti di fatturazione, ordini di vendita, business partner, giacenze di materiale e prodotti, più s4_guide, una guida a filtri, servizi analitici e KPI. Si installa con Basic auth, e puoi passare il connettore a OAuth 2.0. L'adapter SAP S/4HANA Cloud ha gli stessi tool integrati come s4_cloud_* sulle API dei suoi communication arrangement.

Se preferisci leggere direttamente le tabelle di S/4HANA, vedi SAP S/4HANA via HANA SQL.

Impostazioni

Ogni impostazione può contenere {{VARIABLES}} dalle variabili d'ambiente del connettore.

Prompt da provare

• "Quali servizi del catalogo riguardano i documenti di fatturazione?"
• "Descrivi l'entità ordine di vendita: quali campi sono importi, e in che valuta?"
• "Fatturato netto per organizzazione commerciale a settembre, dai documenti di fatturazione."
• "Mostra l'ordine di vendita 1 con tutte le posizioni."
• Su Northwind: "Quali dieci prodotti hanno il prezzo unitario più alto, e quale fornitore li consegna?"

FAQ

Quali versioni di OData sono supportate? V2 e V4. La versione viene rilevata da $metadata; puoi forzarla nelle impostazioni.

Devo prima convertire $metadata in OpenAPI? No. Il connettore OData legge $metadata direttamente, e Import Tools → OData $metadata crea i tool a partire da lì.

Claude può modificare dati tramite OData? Non con i cinque tool integrati, che leggono soltanto. Le scritture richiedono tool che importi o scrivi tu, e un ruolo del server MCP può escluderli; le scritture su SAP recuperano il token CSRF in automatico.

Funziona con SAP S/4HANA on-premise ed ECC? Sì, tramite SAP Gateway, con un AnythingMCP self-hosted che lo raggiunga. L'adapter SAP S/4HANA (OData) è il modo più rapido per iniziare con S/4HANA.

Come vengono gestiti i risultati grandi? Una query restituisce al massimo 1.000 righe. Il connettore segue il paging del server sullo stesso host e restituisce nextSkip, così il modello può chiedere la pagina successiva.

Funziona anche con ChatGPT e Copilot? Sì. Lo stesso server MCP funziona in Claude, ChatGPT, GitHub Copilot, Cursor e Claude Code.

Guide correlate

• Collegare SAP a Claude: tutti i connettori SAP in sintesi
• SAP S/4HANA via HANA SQL: la via del database, con il data dictionary di SAP come tool
• OpenAPI to MCP: API REST con una specifica OpenAPI o Swagger
• SOAP to MCP: servizi WSDL
• OData nella documentazione di AnythingMCP