Transmedia MCP Server

Configurazione diretta in Codex

Aggiungi questa sezione a ~/.codex/config.toml. Su Windows il file si trova normalmente in %USERPROFILE%\.codex\config.toml. Sostituisci YOUR_API_KEY con la chiave del servizio.

[mcp_servers.transmedia]
enabled = true
url = "https://mcp.transmedia.desme.digital/"
startup_timeout_sec = 30
tool_timeout_sec = 180

[mcp_servers.transmedia.http_headers]
x-api-key = "YOUR_API_KEY"

Dopo il salvataggio riavvia Codex per ricaricare la connessione. In chat puoi chiedere: «Usa Transmedia per elencare le categorie disponibili».

Questa configurazione usa l'header x-api-key. bearer_token_env_var è un'alternativa per chi usa un token Bearer: deve indicare il nome di una variabile d'ambiente realmente impostata, non il nome dell'header HTTP.

Documentazione MCP di Codex.

Autenticazione e opzioni

Per accedere ai dati usa uno dei due header equivalenti: x-api-key: YOUR_API_KEY oppure Authorization: Bearer YOUR_API_KEY. La chiave viene inoltrata al backend Transmedia, che applica i permessi dell'account.

initialize e tools/list possono rispondere anche senza chiave. Vedere l'elenco degli strumenti non dimostra che l'accesso al catalogo sia autorizzato: verifica anche una chiamata a list_categories.

Esempio di opzioni aggiuntive in Codex, nella stessa sezione degli header:

[mcp_servers.transmedia.http_headers]
x-api-key = "YOUR_API_KEY"
X-Raw-Context = "true"
X-Transmedia-Url = "https://transmedia.desme.digital"

Altri client MCP

Claude Code

Per rendere Transmedia disponibile in tutti i tuoi progetti, esegui questo comando nel terminale. La riga singola funziona anche in PowerShell:

claude mcp add --transport http --scope user --header "x-api-key: YOUR_API_KEY" transmedia https://mcp.transmedia.desme.digital/

Sostituisci YOUR_API_KEY con la tua chiave. Lo scope user salva la connessione personale in ~/.claude.json. Usa --scope local per limitarla al progetto corrente mantenendola privata.

In alternativa, crea .mcp.json nella radice del progetto. Questo esempio usa una variabile d'ambiente per la chiave:

{
  "mcpServers": {
    "transmedia": {
      "type": "http",
      "url": "https://mcp.transmedia.desme.digital/",
      "headers": {
        "x-api-key": "${TRANSMEDIA_API_KEY}"
      }
    }
  }
}

Imposta la variabile prima di avviare Claude Code, scegliendo il comando della tua shell:

# PowerShell (sessione corrente)
$env:TRANSMEDIA_API_KEY = "YOUR_API_KEY"

# Bash / Zsh (sessione corrente)
export TRANSMEDIA_API_KEY="YOUR_API_KEY"

La configurazione .mcp.json ha scope project: Claude Code può chiedere di approvarla al primo utilizzo. La variabile deve essere disponibile nell'ambiente da cui avvii Claude Code.

Controlla la connessione dal terminale e, nella sessione interattiva, con /mcp:

claude mcp list
claude mcp get transmedia

Prova quindi: «Usa Transmedia per elencare le categorie disponibili». Per abilitare il contesto RAG grezzo aggiungi "X-Raw-Context": "true" alla sezione headers.

Configurazione MCP di Claude Code.

OpenCode

Inserisci il server in opencode.json. Per questa autenticazione con API key, disattiva l'avvio automatico di OAuth.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "transmedia": {
      "type": "remote",
      "url": "https://mcp.transmedia.desme.digital/",
      "enabled": true,
      "oauth": false,
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

Configurazione MCP in OpenCode.

Cline

Apri la gestione MCP di Cline, aggiungi un server remoto e seleziona Streamable HTTP. Imposta https://mcp.transmedia.desme.digital/ come URL e x-api-key come header di autenticazione. Usa il file di configurazione aperto da Cline: .claude/settings.json non è la configurazione MCP di Cline.

Guida MCP di Cline.

Continue

Aggiungi questo blocco alla sezione mcpServers di config.yaml. Gli strumenti sono disponibili in modalità Agent.

mcpServers:
  - name: Transmedia
    type: streamable-http
    url: https://mcp.transmedia.desme.digital/
    requestOptions:
      headers:
        x-api-key: YOUR_API_KEY

Guida MCP di Continue.

Claude Desktop e ChatGPT sul web

La configurazione locale di Codex non si trasferisce automaticamente ad altri prodotti. Per collegare il server da un'interfaccia web, usa la procedura per i connettori remoti del prodotto e verifica che supporti l'autenticazione richiesta dal servizio.

Questo server inoltra una API key: non implementa un flusso OAuth. Un connettore che non permette di impostare gli header di autenticazione non potrà accedere ai dati con la sola URL. Le connessioni locali di Claude Desktop basate su command e args richiedono un client o bridge dedicato per raggiungere un server HTTP.

Verifica manuale

Gli esempi seguenti usano la sintassi di una shell POSIX. Su PowerShell usa curl.exe e adatta le continuazioni di riga, oppure usa MCP Inspector.

1. Inizializzazione

curl -X POST https://mcp.transmedia.desme.digital/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"manual-test","version":"1.0"}}}'

Atteso: risposta JSON-RPC con lo stesso id, result.serverInfo.name = "transmedia-library" e capacità tools.

2. Conferma dell'inizializzazione

curl -i -X POST https://mcp.transmedia.desme.digital/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

Atteso: 202 Accepted senza corpo. Le notifiche non hanno un id.

3. Elenco degli strumenti

curl -X POST https://mcp.transmedia.desme.digital/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":"tools-1","method":"tools/list","params":{}}'

Atteso: result.tools con 15 definizioni.

4. Lettura autenticata

curl -X POST https://mcp.transmedia.desme.digital/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{"jsonrpc":"2.0","id":"read-1","method":"tools/call","params":{"name":"list_categories","arguments":{}}}'

Atteso: result.isError = false e categorie in result.content. Controlla il contenuto della risposta: un errore del backend può essere restituito come risultato MCP con isError: true, anche quando lo stato HTTP è 200.

Comportamento HTTP e SSE

• POST /: richieste JSON-RPC; risposte JSON oppure SSE in base all'header Accept.
• Le risposte SSE usano event: message e data: con un oggetto JSON-RPC. Lo stream termina dopo la risposta finale. Non viene inviato un evento endpoint.
• GET / da browser: questa pagina HTML. GET / con Accept: text/event-stream: 405, perché il server non offre un canale SSE standalone.
• OPTIONS /: 204 per il preflight CORS. Il server non assegna un Mcp-Session-Id.
• Durante le chiamate streaming, le notifiche notifications/progress vengono inviate solo se la richiesta contiene params._meta.progressToken.

Specifica dei trasporti MCP.

Strumenti disponibili

Gli schemi aggiornati e i parametri obbligatori vengono restituiti da tools/list.

Usare il catalogo e verificare le fonti

1. Se l'item non è noto, usa ask_organization o ask_library per identificare gli item rilevanti. Per cercare per parola chiave usa list_items.
2. Leggi i dettagli con get_item e, se serve, esplora le relazioni.
3. Verifica i passaggi citati con get_chunks; usa resolve_labels per associare ogni citazione a una fonte leggibile.
4. Per approfondimenti su un item usa ask_item. Riporta le fonti insieme alla risposta.

Problemi frequenti

Gli strumenti non compaiono

Controlla URL, trasporto Streamable HTTP, server abilitato e caricamento della configurazione. Riavvia il client e verifica initialize e tools/list.

«connection closed: initialize response» o errore di deserializzazione

Verifica che tutti i file aggiornati siano stati pubblicati, inclusi index.php e mcp/errors.php. Il POST non deve iniziare con event: endpoint.

401 / Invalid or missing API key

Controlla la chiave e l'header di autenticazione. Un elenco strumenti riuscito non verifica la chiave.

403

La chiave non autorizza la risorsa o il modello richiesto. Controlla ruolo e ambito di accesso.

429

È stato raggiunto il limite di richieste. Rispetta il valore dell'header Retry-After.

Timeout nelle risposte AI

Controlla timeout del client e del backend. Per il percorso streaming, verifica che il proxy non accumuli gli eventi SSE prima di inoltrarli.

405 sulla GET SSE

È il comportamento previsto: il client deve inizializzare la connessione con un POST Streamable HTTP.