MCP setup

Quey exposes browser captures to coding agents through the Model Context Protocol. Register the MCP server with your agent so it can read captures, make edits, and stream results back.

Register with your agent

If you ran quey init during setup and said yes when it asked about registering an agent, this is already done. Otherwise, use the quey mcp add command to auto-register, or add the entry to .mcp.json manually:

terminalbash

1quey mcp add

Or manually create .mcp.json at your project root:

.mcp.jsonjson

1{2  "mcpServers": {3    "quey": {4      "command": "npx",5      "args": ["-y", "@quey/mcp", "server"]6    }7  }8}

Note

Claude Code auto-detects .mcp.json when it exists in the project root — no additional setup needed.
Cursor respects .mcp.json in the project root. You can also add it manually in Settings → MCP.

Other agents

For Codex, Windsurf, Zed, VS Code, Cline, Gemini CLI, and other MCP-aware agents, quey add delegates to add-mcp, which knows each agent's config file and format:

terminalbash

1quey add all       # register with every agent add-mcp supports, after you confirm what it'll write and where2quey add other     # pick from add-mcp's full agent list interactively3quey add codex     # or any other agent slug, e.g. windsurf, zed, vscode

Note

Some agents (Claude Desktop, Cline, Cline CLI, Goose, Windsurf, Antigravity) have no project-level config format — only a machine-wide one. quey add all/quey add <agent> always shows exactly what will be written and where, and asks you to confirm, before touching anything outside this project.

Tip

Auto-run is on by default but harmless without QUEY_CODEX_CWD — with no target repo set, a capture just records an error asking you to set it. See Configuration to point it at a repo.

The MCP server runs in combined mode by default: the HTTP bridge (for the extension) and MCP stdio (for agents) run in the same process, so captures are shared immediately.

Tools reference

These MCP tools are available to any connected agent:

Tool	Description
`quey_list_sessions`	List all capture sessions with counts.
`quey_get_session`	Get a session with all its captures.
`quey_get_pending`	Get unacknowledged captures, optionally by session.
`quey_get_capture`	Get full capture details including element context and thread.
`quey_acknowledge`	Mark a capture as seen / in-progress.
`quey_resolve`	Mark a capture as resolved with a summary.
`quey_dismiss`	Dismiss a capture with a reason.
`quey_reply`	Add a message to a capture's thread.
`quey_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

1# Health check2curl http://localhost:4747/health3 4# List pending captures5curl http://localhost:4747/captures/pending6 7# Get a specific capture8curl http://localhost:4747/captures/<id>9 10# Subscribe to real-time events (SSE)11curl -N http://localhost:4747/events