MAPSHROOM / MODEL CONTEXT PROTOCOL

La tua AI.
I tuoi shader.

Descrivi un effetto. Guardalo prendere forma. Portalo nel tuo mapping. Collega il tuo assistente a Mapshroom con un indirizzo pubblico.

01 / LA TUA IDEA

«Crea onde di luce lente, con colori che posso regolare.»

02 / MAPSHROOM MCPmapshroom.dev/api/mcpHTTPS · Streamable HTTP
03 / IL TUO WORKSPACE

Anteprima → Open on Mapshroom

Shader, controlli e link pronto da aprire.
01CollegaAggiungi l’URL nella tua app AI.
02CreaChiedi un effetto, poi regola i controlli.
03ApriPorta lo shader nel workspace.
01

UN INDIRIZZO PUBBLICO

Collega la tua app.

MCP è il protocollo con cui un assistente usa gli strumenti di Mapshroom. Il server remoto è online: funziona anche quando il computer su cui hai installato il server locale è spento. Aggiungilo una volta nelle impostazioni MCP dell’app che vuoi usare.

URL del server remoto
https://mapshroom.dev/api/mcp

Trasporto: Streamable HTTP. Autenticazione: nessuna. Non servono Node.js o un file da scaricare per la connessione remota. L’accesso e le funzionalità dell’app AI dipendono dal suo piano e dalle impostazioni del workspace.

Cursor

Unisci questa voce a ~/.cursor/mcp.json per tutte le tue cartelle, oppure a .cursor/mcp.json nel progetto. Conserva le altre voci e riavvia la connessione MCP. Per Cursor sul web, aggiungi lo stesso URL nelle impostazioni delle integrazioni remote.

mcp.json
{
  "mcpServers": {
    "mapshroom": {
      "url": "https://mapshroom.dev/api/mcp"
    }
  }
}
Documentazione Cursor ↗
Codex

Aggiungi un server HTTP nelle impostazioni MCP, oppure esegui questo comando. Se esiste già un server locale chiamato mapshroom, usa un nome diverso per mantenerli entrambi.

CLI
codex mcp add mapshroom-remote --url https://mapshroom.dev/api/mcp
Documentazione Codex ↗
Claude Code
CLI
claude mcp add --transport http mapshroom https://mapshroom.dev/api/mcp
Documentazione Claude Code ↗
VS Code

Usa MCP: Add Server e scegli HTTP, oppure unisci questa configurazione a .vscode/mcp.json.

.vscode/mcp.json
{
  "servers": {
    "mapshroom": {
      "type": "http",
      "url": "https://mapshroom.dev/api/mcp"
    }
  }
}
Documentazione VS Code ↗
ChatGPT, Claude & altre app

Se l’app consente un connettore MCP personalizzato, inserisci l’URL remoto e scegli nessuna autenticazione. Abilita il connettore nella conversazione. La presenza dell’app su un telefono non garantisce il supporto ai connettori personalizzati: controlla le funzioni del client e del tuo account. Se mancano, usa un client compatibile e apri sul telefono il link allo shader.

ChatGPT ↗ · Claude ↗

02

UN MESSAGGIO DA COPIARE

Fallo configurare al tuo agente.

Invia questo messaggio al tuo agente. Può leggere le istruzioni pubbliche senza eseguire JavaScript. Se non ha accesso alle impostazioni, ti guiderà nella configurazione.

Messaggio per il tuo agente
Leggi https://mapshroom.dev/mcp/agents.md e configura Mapshroom MCP in questa app usando https://mapshroom.dev/api/mcp (Streamable HTTP, nessuna autenticazione). Conserva gli altri server configurati. Verifica initialize, tools/list, get_mapshroom_context e get_shader_spec. Se non puoi modificare la configurazione, indicami i passaggi esatti. Poi crea uno shader con anteprima e un link per aprirlo in Mapshroom.

Leggere una pagina o scrivere “usa Mapshroom” non installa automaticamente un MCP. Gli strumenti devono essere aggiunti e abilitati nel client.

03

DALL’IDEA ALLO SHADER

Crea, guarda, apri.

Prova questo prompt
Usa Mapshroom MCP. Leggi get_mapshroom_context e get_shader_spec, poi crea uno shader con onde luminose lente e controlli per velocità e intensità. Mostrami un’anteprima, poi dammi il link per aprirlo in Mapshroom.
  1. L’assistente legge il formato GLSL di Mapshroom e scrive lo shader.
  2. Se l’app supporta MCP Apps o HTML/WebGL, visualizza l’anteprima interattiva. Altrimenti restituisce un link all’anteprima nel browser.
  3. Regola i controlli e premi Open on Mapshroom. Il link contiene lo shader e i valori correnti; il rendering avviene sul dispositivo.
  4. Lo shader viene aggiunto al workspace nello stesso browser e profilo. Su un altro dispositivo si apre il suo workspace locale: i progetti non si sincronizzano tramite MCP.

FOTO → PROFONDITÀ → LUCE

Lo shader deve conoscere il suo input.

Il nuovo strumento get_mapshroom_context spiega all’agente cos’è Mapshroom, come preparare foto, depth map e maschere, e cosa legge realmente lo shader. Il calcolo della profondità avviene nell’app sul tuo dispositivo; il server MCP fornisce istruzioni, controlli e link.

Prova le curve luminose su una depth map sintetica: bianco vicino, nero lontano. Regola bande, velocità e colore. Per riprodurre il risultato nel workspace, scarica la mappa; nello shader scegli Load Asset → Import image → Use selection. Il link porta soltanto lo shader e i controlli.

Prova il workflow depth
Usa Mapshroom MCP. Leggi get_mapshroom_context e get_shader_spec. Mostrami l’esempio depth-contours con previewInput demo-depth, poi dammi il link per aprirlo in Mapshroom e la depth map da selezionare nel workspace.
04

OPZIONALE / SUL TUO COMPUTER

Invia a una scheda già aperta.

Per far aggiungere uno shader direttamente dall’assistente senza aprire un link, usa il server locale sullo stesso computer del browser. Questa modalità usa un codice temporaneo; il server remoto non genera codici di connessione.

Installa il server locale
  1. Installa Node.js 22 o superiore e scarica il file qui sotto.
  2. Aggiungi la configurazione STDIO alla tua app. Sostituisci il percorso con quello completo del file scaricato.
  3. Riavvia la connessione MCP e chiedi get_workspace_connection. Nel workspace, premi MCP accanto a History e incolla il codice. Consenti l’accesso alla rete locale se richiesto.
Scarica mapshroom-mcp.mjs
STDIO / Node.js
{
  "mcpServers": {
    "mapshroom-local": {
      "command": "node",
      "args": [
        "/absolute/path/mapshroom-mcp.mjs"
      ]
    }
  }
}

Su Windows usa barre / nel percorso JSON. Un riavvio del server cambia il codice: collega nuovamente la scheda. Per VS Code usa servers al posto di mcpServers e type: stdio.

SE QUALCOSA NON TORNA

Trova il punto da sistemare.

L’agente non riconosce Mapshroom

Aggiungi l’URL MCP nelle impostazioni dell’app, abilita gli strumenti e riavvia la connessione. Un’installazione locale in Codex non configura automaticamente Cursor o il telefono. Verifica tools/list: il remoto espone cinque strumenti, il locale otto.

Vedo una pagina HTML o un errore 404

Usa esattamente https://mapshroom.dev/api/mcp nel client. /mcp/ è la guida; /ai/ è l’anteprima; il file .mjs è per la modalità locale. Un GET al server mostra informazioni, mentre il protocollo MCP usa POST JSON-RPC.

Sul telefono o in chat non vedo l’anteprima

Verifica che il client supporti connettori MCP personalizzati. Per l’anteprima interattiva serve anche MCP Apps o HTML/WebGL. Chiedi il link all’anteprima o il codice GLSL se il client non li supporta.

Errore 429 o servizio temporaneamente non disponibile

Attendi un minuto prima di riprovare. Il server applica limiti alle richieste e ai payload; la disponibilità dipende anche dalle quote di hosting. Puoi usare il server locale come alternativa.

La compatibilità di protocollo è verificata con il client SDK MCP. Le funzioni specifiche di ogni app e account possono variare. La pagina e le istruzioni testuali sono pubbliche e indicizzabili; i motori di ricerca decidono quando indicizzarle.