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

Clone and build
Section titled “Clone and build”
Terminal window
```
git clone https://github.com/CoherentLabs/Gameface-MCP.git
cd Gameface-MCP
npm install
npm run build
```
The build compiles src/ into build/, producing build/index.js. Every client configuration points at that path.
Point it at the Player
Section titled “Point it at the Player”

Create ~/.gameface-mcp/config.json. This file belongs to the machine rather than to a project, because the server is reused across every game repository:
~/.gameface-mcp/config.json
```
{
  "browserExecutable": "D:/path/to/your/sdk/Player/Player.exe",
  "browserArgs": ["--enable-gui=false"],
  "port": 9444,
  "cdpHost": "localhost"
}
```
Every field is optional, and browserArgs are merged into every launch.

The Player’s toolbar and bookmark bar consume an inconsistent portion of the requested height, so the real viewport never matches the requested resolution. Every screenshot and layout assertion is then measured against the wrong canvas. --enable-gui=false removes them.
Wire it into the agent
Section titled “Wire it into the agent”

Select the client below. With the config file from step two in place, the args array needs nothing beyond the path to build/index.js, since the Player path and port are picked up automatically.

Client Configuration

Create .mcp.json at the project root:

{
  "mcpServers": {
    "gameface": {
      "command": "node",
      "args": ["/absolute/path/to/Gameface-MCP/build/index.js"]
    }
  }
}

Create .vscode/mcp.json at the project root. The repository ships one that can be copied directly:

{
  "servers": {
    "gameface_local": {
      "command": "node",
      "args": ["build/index.js"]
    }
  }
}

Use .gemini/settings.json for a single project, or ~/.gemini/settings.json to apply it everywhere:

{
  "mcpServers": {
    "gameface": {
      "command": "node",
      "args": ["/absolute/path/to/Gameface-MCP/build/index.js"],
      "timeout": 30000,
      "trust": false
    }
  }
}

Edit claude_desktop_config.json, found under %APPDATA%/Claude/ on Windows and ~/Library/Application Support/Claude/ on macOS:

{
  "mcpServers": {
    "gameface": {
      "command": "node",
      "args": ["/absolute/path/to/Gameface-MCP/build/index.js"]
    }
  }
}

Available Capabilities

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.