Local MCP: setting up each client

Français · Type: how-to · Audience: author · Context: local Studio · Status: ready · Applies from: 4.2.5

The local Studio · contract: stable · verified by CI (support matrix of 4.4.0, 2026-10-23): Chromium end to end (the Studio's checks); Windows: the unit suite only · automated checks: jobs e2e, windows; CI plan e2e, windows; 2 test files · people's passes: studio-hero-matrix not run (#238) · known limits: no-docs-remote

npm run mcp starts a Model Context Protocol server over stdio that gives any AI assistant the Studio's operations as tools: Claude Code, Claude Desktop, Cursor, Codex CLI, Gemini CLI or a hand-written agent then read and edit a game the way the Studio does, and you see the result live in npm run studio. This page connects each client.

What you get

Your AI client lists a quest-n-click server with tools such as list_rooms, get_room, set_text, validate and solve, working on your game's files.

The server

Started by npm run mcp in the engine repository (tools/mcp/server.ts, SDK @modelcontextprotocol/sdk 1.x). It is named quest-n-click and gives the engine's version.
Tools are defined once in tools/studio/tools.ts, shared with the Studio's Assistant; the list: MCP tools. Two resources: webscumm://game (= list_rooms) and webscumm://room/<id> (= get_room), JSON.
The game is chosen as for every tool: GAME=<id> (or GAME_DIR=<folder>), otherwise the game last chosen with npm run game, otherwise config.game of package.json.
stdout carries the protocol only; logs go to stderr ([quest-n-click mcp] ready: game "<id>" (<folder>)). Use npm run -s mcp (silent) in client configs: without -s, npm prints its > quest-n-click mcp banner on stdout, which strict clients reject.
A failing operation (unknown room, bad path, broken edit…) returns a tool error with the message; the server keeps running.
What the agent is told first: the game and how to work on it. Start with list_rooms and get_room; learn the format with read_doc CONTENT_GUIDE; after any change run validate, then solve, then run_tests; never invent coordinates, ask the human with add_note to place things in the Studio; read AGENTS.md for the rules.
Screenshots need the dev server (npm run studio) at WEB_SCUMM_DEV_URL (default http://localhost:5173/) and Playwright; otherwise the tool says why it is unavailable.

Context and versions

The engine repository, from 4.2.5 (the server's name quest-n-click). A created project runs the same server with npx quest-n-click mcp (below). For a hosted Studio, the remote /mcp or npm run mcp -- --server <url>: Remote MCP.

Prerequisites

Node 22.12 or later, the repository cloned and installed (npm install).
The absolute path of your clone, written /path/to/quest-n-click below.

Where to run the commands

The claude mcp add commands run in the engine repository. The other clients read a configuration file, named in each section; the server then runs in the folder that file gives.

Steps: connect your client

Replace /path/to/quest-n-click with the absolute path of your clone. npm --prefix <folder> run -s mcp runs the script inside <folder> whatever the client's working directory. Add "env": { "GAME": "<id>" } to work on another game.

Claude Code

The repository ships .mcp.json (project scope): open Claude Code in the repository and approve the quest-n-click server.

{ "mcpServers": { "quest-n-click": { "type": "stdio", "command": "npm", "args": ["run", "-s", "mcp"], "env": {} } } }

Or from the command line, in the repository (-s local by default; -s project writes .mcp.json):

# in the engine repository
claude mcp add quest-n-click -- npm run -s mcp
claude mcp add quest-n-click -e GAME=demo -- npm --prefix /path/to/quest-n-click run -s mcp

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
```
{ "mcpServers": { "quest-n-click": { "command": "npm", "args": ["--prefix", "/path/to/quest-n-click", "run", "-s", "mcp"] } } }
```
Claude Desktop does not start from your shell, so it may not find npm (no shell PATH). Then put npm's absolute path in command: the output of which npm in a terminal, for instance "command": "/usr/local/bin/npm".

Cursor

The repository ships .cursor/mcp.json (project). The same block in ~/.cursor/mcp.json works for every project, with an absolute path instead of ${workspaceFolder}:
```
{ "mcpServers": { "quest-n-click": { "command": "npm", "args": ["--prefix", "${workspaceFolder}", "run", "-s", "mcp"] } } }
```

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.quest-n-click]
command = "npm"
args = ["--prefix", "/path/to/quest-n-click", "run", "-s", "mcp"]
# env = { GAME = "demo" }

Gemini CLI

Add to ~/.gemini/settings.json (or .gemini/settings.json in the repository):

{ "mcpServers": { "quest-n-click": { "command": "npm", "args": ["run", "-s", "mcp"], "cwd": "/path/to/quest-n-click" } } }

Any other client

Command npm run -s mcp (or npx tsx tools/mcp/server.ts) with the repository as working directory, transport stdio. Node 22.12+.

In a created project

A created project has no mcp script; its engine command starts the same server for the project's game. In any of the configurations above, use npx with the arguments quest-n-click mcp, the project folder as working directory:

# in the created project
claude mcp add quest-n-click -- npx quest-n-click mcp

The repository's .mcp.json and .cursor/mcp.json are not copied into a created project: write the client's file yourself.

Reading the documentation through MCP

Applies from 4.5.0

From 4.5.0, three tools read this wiki (tools/studio/tools.ts):

search_docs { query, lang?, audience?, context?, version?, type?, includeArchived?, limit?, cursor? }: words or a question in French or English; each result is id#section with its title, type, context, versions, status, score, the reason of the match and an excerpt. No confident match gives an empty list and the index pages to try.
list_docs { audience?, context?, type?, lang?, state? }: the pages there are to read, with their section ids.
read_doc { id, section?, lang?, maxChars?, cursor? }: one page or one section, with where the text comes from (version, commit, doc revision) at its top; maxChars is 20,000 by default, 100,000 at most, and a cursor gives the rest.

read_doc { name } still answers as in 4.4.0: one of the eight historical pages (CONTENT_GUIDE, ENGINE, TOOLS, STUDIO, WORKFLOW, AUDIO, UPGRADING, CLASSICS), whole, in one text block; the other arguments are then ignored. Since 4.5.0 that page is rebuilt from the wiki's sections in the old page's order (wiki/legacy.json), within 1.5 times its 4.4.0 size: when the sections say more, the longest give their heading, their first paragraph and the read_doc { id, section } that returns the rest. Giving both name and id, or neither, is a tool error: give either name (one of the 8 legacy pages) or id, not both. In the engine repository the tools read wiki/ as it is (draft pages included, said so in the provenance); in an installed package they read its documentation bundle (ready pages only).

Limit · no-docs-remote A hosted Studio's remote /mcp offers neither read_doc nor search_docs nor list_docs: an agent working on a hosted Studio reads the documentation through the local stdio server of the same engine version.

Any AI, not one AI

AGENTS.md at the repository root is the vendor-neutral operating manual; CLAUDE.md points to it.
Every MCP client connects the same way, with the configuration above.
An AI without MCP still works: it edits the files, the Studio reloads (it watches them), you see the result and answer in Notes or in the Storyboard, and the AI reads notes.json back (Notes). Git carries the history. A typical session: Working with an AI.

Expected result, and how to check it

The client lists the quest-n-click server as connected, with its tools. Ask it to call list_rooms: it answers with the game's id, title, rooms and characters. In Claude Code, claude mcp list shows the server.

Common errors

Symptom	Cause	Fix
The client rejects the server, an "invalid JSON" or parse error at start	npm's banner on stdout	Use `npm run -s mcp` (with `-s`)
Claude Desktop: the server fails to start, `npm` not found	No shell `PATH`	Put npm's absolute path (`which npm`) in `command`
The tools work on another game	`GAME` or the game last chosen	Add `"env": { "GAME": "<id>" }`
`screenshot` says it is unavailable	No dev server at `WEB_SCUMM_DEV_URL`, or no Playwright	Start `npm run studio`; install Playwright
`reading by id needs the documentation of wiki/, not available here`	No wiki or bundle where the server runs	Use `read_doc { name }`, or a 4.5.0 engine

More: Studio troubleshooting.

Files or data changed

The client's configuration file only (.mcp.json with claude mcp add -s project). The server writes the game's files when a tool writes, as the Studio would.

References

Edit the source of this page · Report an error