# Connect an MCP agent

## Before you start

[Install QH Pixels](/docs/qh-pixels/install). Use an agent client that supports standard local stdio MCP. Both the studio and MCP server must point to the same checkout and its local SQLite documents.

## Configure the connection

1. Add this server to your agent client’s MCP configuration. Replace the example path with the absolute path to your checkout:

   ```json
   {
     "mcpServers": {
       "qh-pixels": {
         "command": "node",
         "args": ["/absolute/path/qh-pixels/server/mcp.mjs"]
       }
     }
   }
   ```

2. Restart or reconnect the client. Ensure its `node` executable is Node.js 24 or newer.
3. Ask the agent to read `qh://protocol`, list workspaces and models, and inspect the selected project before making changes.
4. Use the [portable QH Pixels skill](https://github.com/qentrah/qh-pixels/tree/main/skill/qh-pixels) when your agent supports skills.

The agent should discover the QH Pixels tools, and its changes should appear in the preview studio. Inference stays in the external agent; the browser does not run an image-generation service.

## Edit and export carefully

Use `read_region` and `preview_frame` to inspect a small region or frame. Batch numeric edits with `apply_operations` and the current revision. On a conflict, reread the project before retrying. Revision restore retains previous local edits.

`export_project` supports PNG, sprite sheets, JSON, GIF, and MP4. Read the [tool protocol](https://github.com/qentrah/qh-pixels/blob/main/docs/PROTOCOL.md) for the exact arguments. Do not invent intermediate poses: playback repeats held frames. Use PNG or JSON when exact pixel data matters.

If the client cannot start the server, verify the absolute script path, Node version, and installed dependencies. If studio changes do not appear, check that both processes use the same checkout and database.