MAPSHROOM / MODEL CONTEXT PROTOCOL

Your AI.
Your shaders.

Describe an effect. Watch it take shape. Bring it into your mapping. Connect your assistant to Mapshroom with a public server address.

Set up MCP Agent instructions ↗

01 / YOUR IDEA

“Create slow waves of light, with colors I can adjust.”

02 / MAPSHROOM MCPmapshroom.dev/api/mcpHTTPS · Streamable HTTP

03 / YOUR WORKSPACE

Preview → Open on Mapshroom

Shader, controls and a link ready to open.

01ConnectAdd the URL in your AI app.

02CreateAsk for an effect, then adjust its controls.

03OpenBring the shader into your workspace.

ONE PUBLIC ADDRESS

Connect your app.

MCP is the protocol your assistant uses to call Mapshroom tools. The remote server is online, even when the computer running your local server is off. Add it once in the MCP settings of the app you want to use.

Remote server URL

https://mapshroom.dev/api/mcp

Transport: Streamable HTTP. Authentication: none. No Node.js or downloaded file is needed for the remote connection. AI app access and features depend on its plan and workspace settings.

Cursor

Merge this entry into ~/.cursor/mcp.json for all your folders, or .cursor/mcp.json in the project. Keep other entries and restart the MCP connection. For Cursor on the web, add the same URL in its remote integration settings.

mcp.json

{
  "mcpServers": {
    "mapshroom": {
      "url": "https://mapshroom.dev/api/mcp"
    }
  }
}

Cursor documentation ↗

Codex

Add an HTTP server in MCP settings, or run this command. If a local server is already named mapshroom, use a different name to keep both.

CLI

codex mcp add mapshroom-remote --url https://mapshroom.dev/api/mcp

Codex documentation ↗

Claude Code

CLI

claude mcp add --transport http mapshroom https://mapshroom.dev/api/mcp

Claude Code documentation ↗

VS Code

Use MCP: Add Server and choose HTTP, or merge this configuration into .vscode/mcp.json.

.vscode/mcp.json

{
  "servers": {
    "mapshroom": {
      "type": "http",
      "url": "https://mapshroom.dev/api/mcp"
    }
  }
}

VS Code documentation ↗

ChatGPT, Claude & other apps

If your app supports a custom MCP connector, enter the remote URL and select no authentication. Enable the connector in the conversation. A mobile app does not automatically support custom connectors: check the client and account features. If unavailable, use a compatible client and open the shader link on your phone.

ChatGPT ↗ · Claude ↗

ONE MESSAGE TO COPY

Let your agent set it up.

Send this message to your agent. It can read the public instructions without running JavaScript. If it cannot access your settings, it can guide you through setup.

Message for your agent

Read https://mapshroom.dev/mcp/agents.md and configure Mapshroom MCP in this app using https://mapshroom.dev/api/mcp (Streamable HTTP, no authentication). Preserve other configured servers. Verify initialize, tools/list and get_shader_spec. If you cannot change the configuration, give me the exact steps. Then create a shader with a preview and a link to open it in Mapshroom.

Agent guide in Markdown llms.txt JSON configuration

Reading a page or writing “use Mapshroom” does not automatically install an MCP server. Tools must be added and enabled in the client.

FROM IDEA TO SHADER

Create, preview, open.

Try this prompt

Use Mapshroom MCP. Read get_shader_spec and create a shader with slow light waves and controls for speed and intensity. Show me a preview, then give me the link to open it in Mapshroom.

Your assistant reads the Mapshroom GLSL format and writes the shader.
If the app supports MCP Apps or HTML/WebGL, it shows an interactive preview. Otherwise it returns a browser preview link.
Adjust the controls and choose Open on Mapshroom. The link contains the shader and current values; rendering happens on the device.
The shader is added to a workspace in the same browser and profile. On another device it opens that device’s local workspace: MCP does not synchronize projects.

OPTIONAL / ON YOUR COMPUTER

Send to an open tab.

To let your assistant add a shader directly without opening a link, run the local server on the same computer as your browser. This mode uses a temporary pairing code; the remote server does not generate pairing codes.

Install the local server

Install Node.js 22 or newer and download the file below.
Add the STDIO configuration to your app. Replace the path with the full path of the downloaded file.
Restart the MCP connection and request get_workspace_connection. In the workspace, click MCP beside History and paste the code. Allow local network access if requested.

Download mapshroom-mcp.mjs

STDIO / Node.js

{
  "mcpServers": {
    "mapshroom-local": {
      "command": "node",
      "args": [
        "/absolute/path/mapshroom-mcp.mjs"
      ]
    }
  }
}

On Windows use forward slashes in the JSON path. Restarting the server changes its code: pair the tab again. For VS Code use servers instead of mcpServers and type: stdio.

WHEN SOMETHING DOES NOT CONNECT

Find what needs fixing.

The agent does not recognize Mapshroom

Add the MCP URL in the app settings, enable tools and restart the connection. A local Codex installation does not also configure Cursor or your phone. Check tools/list: remote exposes four tools, local exposes seven.

I get an HTML page or a 404

Use exactly https://mapshroom.dev/api/mcp in your client. /mcp/ is the guide; /ai/ is the preview; the .mjs file is for local mode. A GET to the server returns information; MCP uses JSON-RPC POST.

No preview on my phone or in chat

Check that your client supports custom MCP connectors. Interactive previews also require MCP Apps or HTML/WebGL. Ask for the browser preview link or GLSL code if the client does not support them.

429 or temporarily unavailable service

Wait a minute before retrying. The server limits requests and payloads; availability also depends on hosting quotas. The local server is an alternative.

Protocol compatibility is verified with the MCP SDK client. Features in individual apps and accounts may vary. This page and the text instructions are public and crawlable; search engines decide when to index them.