# Mapshroom MCP — agent setup and use

Updated: 2026-09-18. Server version: 0.4.0.

## Public connection

- Endpoint: **https://mapshroom.dev/api/mcp**
- Transport: **Streamable HTTP**, JSON-RPC over HTTPS POST.
- Authentication: **none**. Do not run OAuth login or request a Mapshroom API key.
- Human guide: https://mapshroom.dev/mcp/ (Italian: https://mapshroom.dev/it/mcp/).
- Configuration: https://mapshroom.dev/mcp/client-config.json.
- /mcp/ is an HTML guide, /ai/ is a browser preview, and the .mjs download is a local STDIO executable. None of those is the remote endpoint.
- This is a stateless server: no MCP session ID, no persistent SSE stream, no project storage. The user's computer can be off.

## When asked to configure the integration

1. Identify the actual MCP client. Preserve other server entries and user settings.
2. For Cursor desktop, merge the following into ~/.cursor/mcp.json (global) or .cursor/mcp.json (project). Do not overwrite an existing local mapshroom entry: use mapshroom-remote if both are needed.

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

For VS Code, use .vscode/mcp.json with `servers` instead of `mcpServers` and `"type": "http"` inside the server entry. For Codex: `codex mcp add mapshroom-remote --url https://mapshroom.dev/api/mcp`. For Claude Code: `claude mcp add --transport http mapshroom https://mapshroom.dev/api/mcp`.

For a web/mobile AI app, add the URL through its custom MCP connector settings if available. Configuration, account eligibility, tool access and preview support depend on the client. Merely naming Mapshroom in a prompt does not install a connector. Installing in one app does not configure the others. If you cannot edit settings, give exact instructions instead of claiming installation.

3. Enable the server and reload its connection. Use a fresh conversation if tool discovery is cached.
4. Verify MCP `initialize`, `notifications/initialized`, `tools/list`, then `tools/call` for `get_mapshroom_context` and `get_shader_spec`. Report actual results. A 200 response to GET alone does not prove MCP initialization.

## Protocol diagnostic

POST the following JSON to the endpoint with `Content-Type: application/json` and `Accept: application/json, text/event-stream`:

```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"mapshroom-diagnostic","version":"1.0"}}}
```

Use the negotiated protocol version in `MCP-Protocol-Version` on subsequent requests. Send `{"jsonrpc":"2.0","method":"notifications/initialized"}`, then `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`. Notifications return HTTP 202. Stateless tool calls do not require a persistent connection.

## Five remote tools

| Tool | Purpose |
| --- | --- |
| get_mapshroom_context | Read first: product, photo → depth → shader workflow, input semantics, limitations and three runnable examples. No arguments. |
| get_shader_spec | Read the processColor GLSL ABI, supported controls and a working example before creating code. No arguments. |
| preview_shader | Validate a shader and return an MCP Apps preview resource plus a browser preview URL. |
| get_inline_preview | Return a self-contained HTML/WebGL fragment for a host with native rendering support. |
| get_shader_delivery | Return a compressed importUrl and GLSL with adjusted values. This tool itself does not modify a workspace. |

The three shader tools accept `code` (string, at most 32768 characters, also subject to a 32 KiB UTF-8 validation limit), optional `uniforms` (mapping of control names to numbers, booleans or RGB arrays of exactly three numbers), and optional `shaderId` (1–80 letters, digits, underscores or hyphens). Read tools/list for the authoritative JSON schemas. At most 32 controls and 64 KiB per HTTP request. Retry a 429 after the Retry-After interval. Hosting quotas may also limit availability; the local server is a fallback.

The context is also a Markdown resource at `mapshroom://docs/context/v1` and a public document at https://mapshroom.dev/mcp/context.md. It is generated from one versioned source; resources are not automatically read by every client. The context tool returns the full guide as text as well as structured examples.

The two preview tools also accept optional `previewInput: "neutral" | "demo-depth"`. Test depth effects using the depth-contours example returned by get_mapshroom_context and `previewInput: "demo-depth"`. Direct browser demonstration: https://mapshroom.dev/ai/?example=depth-contours. The matching sample image is https://mapshroom.dev/mcp/demo-depth.png. Load the image separately in Mapshroom; it is not carried in shader links. There is no automatic input conversion or depth-generation tool.

## Shader workflow

1. Call get_mapshroom_context, then get_shader_spec. Establish the input kind (photo, grayscale depth, mask or procedural) and follow the returned contract. Do not invent a ShaderToy mainImage entry point.
2. Use preview_shader for MCP Apps, or get_inline_preview if the host can actually render HTML/WebGL. Never claim an in-chat preview appeared when only text or a file was returned. Use the returned browser preview URL when rendering is unsupported.
3. After acceptance or an explicit request for a link, use get_shader_delivery. Preserve shaderId and adjusted uniforms for retries of the same shader. Present importUrl as an ordinary clickable link labeled Open on Mapshroom; GLSL is the copy fallback.
4. Opening the link adds to the local browser's workspace, preserving existing work. Different devices/profiles have different local projects. MCP does not synchronize projects or read local images. Images selected for preview stay on that device.

The remote server DOES NOT expose get_workspace_connection, list_workspaces or send_shader_to_workspace. Do not ask a remote user for a pairing code or claim direct delivery into their browser.

## Optional local pairing

Download https://mapshroom.dev/ai/mapshroom-mcp.mjs and run it via STDIO with Node.js 22 or newer. Configure command `node`, args `["/absolute/path/mapshroom-mcp.mjs"]` on the same computer as the Mapshroom browser. Use a separate server name such as mapshroom-local when keeping the remote server. Eight tools are exposed locally, including the three pairing/delivery tools. Obtain get_workspace_connection, let the user paste the private code into MCP beside History, and allow the browser's local-network access if needed. Restarting rotates the code. Never publish private pairing codes. Only report delivery after acknowledgement.

## Official client references

- Cursor: https://cursor.com/docs/mcp
- Codex: https://developers.openai.com/codex/mcp/
- Claude Code: https://code.claude.com/docs/en/mcp
- VS Code: https://code.visualstudio.com/docs/agent-customization/mcp-servers
- ChatGPT: https://developers.openai.com/plugins/deploy/connect-chatgpt

Protocol validation is performed with the MCP SDK client. Individual vendor apps, mobile surfaces and account plans are not all tested end to end. These public pages are crawlable, but search indexing and automatic discovery are not guaranteed.