MCP setup

Quey exposes browser captures to coding agents through the Model Context Protocol. Once registered, your agent can poll for captures, acknowledge them, read the element context and instruction, and resolve them with a summary — all through standard MCP tools.

Warning

The MCP server must run in combined server mode to share captures with the Chrome extension. Running the stdio-only mcp subcommand in a separate process will not receive extension captures. See Server modes below.

Server modes

The Quey provider exposes two named subcommands. The difference matters for which one you point .mcp.json at.

server

Combined mode (recommended)

Runs the HTTP bridge and MCP stdio in the same process. Extension captures are immediately visible to the agent. Use this until capture state is externalized.

mcp

Stdio-only mode

Runs MCP stdio without the HTTP bridge. Does not share in-memory capture state with a separately-running bridge. For advanced setups only.

http

HTTP-only mode

Runs only the HTTP bridge (port 4747). Useful for debugging the extension connection without an agent attached.

Register with Claude Code

Run the mcp add command from inside your project. This writes the correct entry to .mcp.json in the current directory.

terminalbash

uitoolbar mcp add

Or add the entry manually:

.mcp.jsonjson

{
  "mcpServers": {
    "quey": {
      "command": "npx",
      "args": ["-y", "@uitoolbar/mcp", "server"],
      "env": {
        "TOOLBAR_AUTO_RUN": "0",
        "TOOLBAR_CODEX_CWD": "/absolute/path/to/repo"
      }
    }
  }
}

Tip

Claude Code picks up .mcp.json automatically when it exists in the project root. No additional config needed.

Enable auto-run

Set TOOLBAR_AUTO_RUN=1 to have the MCP runner execute Codex or Claude automatically when a capture arrives. Without this, captures queue up for the agent to poll manually.

.mcp.jsonjson

{
  "mcpServers": {
    "quey": {
      "command": "npx",
      "args": ["-y", "@uitoolbar/mcp", "server"],
      "env": {
        "TOOLBAR_AUTO_RUN": "1",
        "TOOLBAR_CODEX_CWD": "/absolute/path/to/repo",
        "TOOLBAR_CODEX_MODEL": "codex-mini-latest"
      }
    }
  }
}

Register with Cursor

In Cursor, go to Settings → MCP and add a new server entry. Use the same config as above but set it up through the UI, or add the .mcp.json file to the project root — Cursor respects it.

Note

Cursor manages its own execution context. Quey's auto-run path detects Cursor as the provider and skips the auto-run step — Cursor handles the file edit itself once the capture is surfaced.

Tools reference

These MCP tools are available to any connected agent:

Tool	Description
`uitoolbar_list_sessions`	List all capture sessions with counts.
`uitoolbar_get_session`	Get a session with all its captures.
`uitoolbar_get_pending`	Get unacknowledged captures, optionally by session.
`uitoolbar_get_capture`	Get full capture details including element context and thread.
`uitoolbar_acknowledge`	Mark a capture as seen / in-progress.
`uitoolbar_resolve`	Mark a capture as resolved with a summary.
`uitoolbar_dismiss`	Dismiss a capture with a reason.
`uitoolbar_reply`	Add a message to a capture's thread.
`uitoolbar_watch`	Block until new captures appear — use in loops for hands-free mode.

HTTP API

The HTTP bridge also exposes a REST API on port 4747. The extension uses this directly; you can also use it for debugging.

terminalbash

# Health check
curl http://localhost:4747/health

# List pending captures
curl http://localhost:4747/captures/pending

# Get a specific capture
curl http://localhost:4747/captures/<id>

# Subscribe to real-time events (SSE)
curl -N http://localhost:4747/events