Server MCP — panoramica
OpenData AI distribuisce tre server FastMCP indipendenti. Possono essere usati dal backend OpenData AI, da Claude Desktop, da un agente MAF/LangGraph o da qualunque altro host MCP. Ogni server supporta sia stdio (per i client locali) sia streamable-http (per il deployment server-side), via la variabile d'ambiente TRANSPORT.
I tre server
| Server | Cosa espone | Tool principali | Host:porta (compose) |
|---|---|---|---|
| ckan-mcp | Qualunque portale CKAN-compatibile (default dati.gov.it). Il base_url è per-call. | package_search, package_show, group_list, organization_list, tag_list, resource_show + altri (11 totali) | http://ckan-mcp:8080/mcp |
| istat-mcp | SDMX 2.1 (default ISTAT). Stessi tool per Eurostat e OCSE cambiando agency + base_url. | list_dataflows, get_dataflow, get_codelist, get_observations, search_dataflows | http://istat-mcp:8081/mcp |
| osm-mcp | OpenStreetMap: geocoding (Nominatim), POI (Overpass), routing (OSRM), e render Leaflet di GeoJSON. | geocode, reverse_geocode, find_pois, route, render_map_html | http://osm-mcp:8082/mcp |
Avvio in locale (stdio)
Modalità tipica per i client desktop (Claude Desktop, Cursor). Il server viene avviato come sotto-processo dal client.
# CKAN MCP via stdio pip install -e ./ckan-mcp-server TRANSPORT=stdio ckan-mcp # Equivalente per ISTAT TRANSPORT=stdio istat-mcp # Equivalente per OSM TRANSPORT=stdio osm-mcp
Per la configurazione concreta di Claude Desktop o Cursor vedi /docs/clients.
Avvio server-side (streamable-http)
Modalità tipica per agenti hostati (MAF, LangGraph, A2A). Espone un endpoint HTTP/JSON-RPC su un path configurabile (/mcp per default).
TRANSPORT=streamable-http \
PORT=8080 MCP_PATH=/mcp \
ckan-mcp
# Verifica rapida (tools/list senza session):
curl -sX POST http://localhost:8080/mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":"1","method":"tools/list"}'Docker e docker-compose
Le immagini ufficiali sono pubblicate su GHCR (ghcr.io/agent-engineering-studio/<server>:<tag>). In compose:
services:
ckan-mcp:
image: ghcr.io/agent-engineering-studio/ckan-mcp-server:main
environment:
TRANSPORT: streamable-http
MCP_PATH: /mcp
PORT: 8080
ports: ["8080:8080"]
istat-mcp:
image: ghcr.io/agent-engineering-studio/istat-mcp-server:main
environment:
TRANSPORT: streamable-http
PORT: 8081
ports: ["8081:8081"]
osm-mcp:
image: ghcr.io/agent-engineering-studio/osm-mcp:main
environment:
TRANSPORT: streamable-http
PORT: 8082
ports: ["8082:8082"]Esempio di chiamata grezza
La sessione streamable-http richiede di gestire l'header mcp-session-id. Per un sanity-check serve solo tools/list:
# Lista tool disponibili
curl -sX POST http://localhost:8080/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{
"jsonrpc":"2.0","id":"1","method":"tools/list"
}' | jq
# Invocazione di package_search su dati.gov.it
curl -sX POST http://localhost:8080/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{
"jsonrpc":"2.0","id":"2","method":"tools/call",
"params":{
"name":"package_search",
"arguments":{
"base_url":"https://www.dati.gov.it/opendata/api/3/action",
"q":"qualità aria",
"rows":5
}
}
}' | jqSicurezza
- I server MCP non implementano autenticazione propria: girano dietro a Traefik / al backend OpenData AI, che espone le funzionalità via REST e A2A autenticati.
- In sviluppo locale, esporli sulla rete è sicuro solo se gli MCP target (CKAN, SDMX, OSM) sono già pubblici, perché i tool fanno fetch lato server.
- Per i casi multi-tenant, mettili dietro un reverse proxy con mTLS o un token statico nelle env (il client MCP lo riusa come header).