Setting up the MCP Server

The Gameface MCP server connects a coding agent to a running Gameface Player through the Chrome DevTools Protocol .

Once connected, the agent reads Gameface’s own warnings, inspects the DOM it produced, captures screenshots, and checks that text fits inside its box, rather than describing what it expects to have built.

Why a Live Engine Is Required

Without a connection, every iteration routes through a person. The agent writes markup, someone runs the Player or Game, someone describes what looks wrong, and the agent revises. What the agent never observes is what Gameface did with its code—the information that settles the question.

The console is the clearest signal. Gameface warns about CSS it cannot resolve, diagnosing Gameface-specific bugs faster than any other available feedback. That warning means nothing while it sits unread.

Prerequisites

Node.js 18+, since the server uses the global fetch API.
A local Gameface SDK with a Player executable. The repository does not ship one, so a Gameface licence and SDK are required. On Windows the executable normally sits at .../Player/Player.exe. Note that Player.exe lives in a Player subfolder under the SDK root rather than at the root itself.
Gameface 3.1.2 or newer, for the reasons covered in Version Awareness.

Installing

Install the server
Section titled “Install the server”

add-mcp detects the installed agents and writes the server into each one’s config.
- Global (recommended)
- Project only
Available in every project on the machine:
Terminal window
npx add-mcp "npx -y gameface-mcp@latest" --name gameface -g
Run from the project folder:
Terminal window
npx add-mcp "npx -y gameface-mcp@latest" --name gameface
A project gameface MCP entry and a global gameface MCP entry compete instead of merging, and only one runs.
Set up the Player
Section titled “Set up the Player”

Start the agent and ask it to launch the Gameface Player. On first launch it asks for the Player path (Player.exe, its folder, or the SDK folder) or offers to search the machine. The path is saved to ~/.gameface-mcp/config.json and reused by every project.

The Player’s toolbar and bookmark bar take an inconsistent part of the requested height, so screenshots and layout assertions measure the wrong canvas. Add "browserArgs": ["--enable-gui=false"] to ~/.gameface-mcp/config.json to remove them.
If you let the agent launch the player and write the config, it will automatically add the "browserArgs": ["--enable-gui=false"] entry for you.
Install the Conductor skill (optional)
Section titled “Install the Conductor skill (optional)”

The Gameface UI Conductor skill clarifies requirements, gets sign-off on a spec, then implements and validates with the MCP tools:
Terminal window
```
npx skills add CoherentLabs/Gameface-MCP --agent claude-code -g
```
Drop -g to install into the current project only. Start a new session afterwards.

Use the --agent flag to specify which client should use the skill. For example, --agent claude-code installs the skill for the Claude Code client.

Client Configuration

add-mcp writes the following entry for each detected client. No manual editing is needed.

Global: ~/.claude.json. Project: .mcp.json.

{
  "mcpServers": {
    "gameface": {
      "command": "npx",
      "args": ["-y", "gameface-mcp@latest"]
    }
  }
}

Global: user mcp.json. Project: .vscode/mcp.json.

{
  "servers": {
    "gameface": {
      "command": "npx",
      "args": ["-y", "gameface-mcp@latest"]
    }
  }
}

VS Code uses servers instead of mcpServers.

Global: ~/.gemini/settings.json. Project: .gemini/settings.json.

{
  "mcpServers": {
    "gameface": {
      "command": "npx",
      "args": ["-y", "gameface-mcp@latest"]
    }
  }
}

%APPDATA%/Claude/claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS.

{
  "mcpServers": {
    "gameface": {
      "command": "npx",
      "args": ["-y", "gameface-mcp@latest"]
    }
  }
}

Available Capabilities

Managing Players with Commands

Commands are shortcuts for launching and managing Players mid development. They appear as slash commands, in Claude Code as /mcp__gameface__<command>. Arguments are positional, and true, yes, y and 1 all count as yes.

/mcp__gameface__launch-player
/mcp__gameface__launch-player http://localhost:3000

Launches the default Player, optionally opening a URL.

/mcp__gameface__launch-player true

Lists every configured Player, sorted by version, and launches the selected one. Useful for testing a UI against several Gameface versions.

Adding Players

Scan the machine
Add a folder

/mcp__gameface__scan-players

Runs a search script inside the server and adds every Player found. The agent only sees the resulting list, not your files. The default Player is unchanged.

/mcp__gameface__add-player

Skips the scan. Provide a Player.exe or a folder of Players, and every Player inside is added. The default Player is unchanged.

Changing the Default

/mcp__gameface__change-player-path asks for a new default Player path. Pass true to search the machine instead.

Tools

These tools are rarely invoked by hand. Knowing what exists establishes what can reasonably be requested, and what to demand evidence of.

Reading What Gameface Did

Tool	Function
`get_console_logs`	Buffered console output plus Log-domain entries, including unsupported-feature warnings
`get_computed_styles`	Computed CSS for a node, meaning what Gameface kept rather than what was written
`get_dom_tree` / `search_dom`	Snapshot of the DOM, or nodes matching a text or XPath query
`take_screenshot`	Full page, viewport, or a custom clip rect
`eval_js`	Runs JavaScript in the connected page
`interact_element`	Click, type, hover, focus, scroll into view, or touch

Checking Layout

Assertion	Check performed
`assert_text_fits`	Whether an element’s content overflows its own box
`assert_no_overlap`	Whether two elements’ rendered boxes intersect
`assert_within_parent`	Whether an element stays inside its parent, an ancestor, or the viewport

Measuring Cost

perf_lint is a static check for expensive layout patterns like align-items: stretch, unsized flex items, and misuse of display: simple. No timing involved, so it does not flake.

perf_measure runs a fixed frame-timing scenario and reports p50, p95, and p99 against a recorded baseline.

Reading the Documentation

Alongside the tools, the server exposes the documentation corpus and the engine constraints as MCP resources, gameface://code-instructions and gameface://rag/<file>.md. The next article covers both.

Version Awareness

Gameface 3.1.2 or newer is required. This version introduced CDP protocol support, including engine logs through the Chrome DevTools Protocol.

The minimum version is verified at connection time via cohtmlVersion. Some older versions have CDP quirks that the server works around, but a tool returning unexpected output may indicate an engine-side gap.

Confirming the Connection

Ask the agent to launch the Player and screenshot the current view. An image and a cohtmlVersion returning together confirm a live connection. A description of what the agent expects the screen to look like means the server is not connected.