Agent API keys (org)

Org-scoped API keys for Cursor, Claude Desktop, and QA agents — one MCP config for all projects.

Agent API keys (vq_org_live_…) authenticate IDE agents and MCP clients against your organization. Use them for Cursor, Claude Desktop, or custom agents that need to read and write across multiple VisualQ projects from a single configuration.

For CI pipelines (GitHub Actions, GitLab, Jenkins), use project API keys (vq_live_…) instead — they are scoped to one project and support the ci scope.

When to use which key

Key type	Prefix	Created in	Best for
Org agent	`vq_org_live_…`	Settings → Agent API Keys	Cursor, Claude Desktop, exploratory QA agents
Project	`vq_live_…`	Project → Settings → API Keys	CI/CD, webhooks, single-project automation

Org agent key capabilities

Access all projects in the organization (pass project slug on each tool call, or set a default project on the key)
Full MCP invoke catalog: VRT analysis, FRT authoring, health, tracking plan, create_project, create_scenario, etc.
Scopes: mcp_read (read-only) or mcp_full (read + write)

Org agent key limits

No ci scope — org keys cannot call /api/ci/* (run_vrt, list_projects, get_run_status via CI routes). Use invoke tools or a project CI key in pipelines.
Org admin required to create or revoke keys
Plan gates still apply (e.g. MCP write tools require Hobby+)

Creating an agent key

Open Agent API Keys

Create a new key

Click New agent key. Choose a name (e.g. Cursor — QA).

Choose scope

mcp_full — read + write (required for create_project, create_scenario, frt_save_feature_draft, run_frt_feature, approve, etc.)
mcp_read — diagnostics only (failures, health, reports)

Default project (optional)

Pick a project slug if you mainly work on one client. The generated MCP config includes VISUALQ_DEFAULT_PROJECT so you can omit project on tool calls.

Copy key and MCP JSON

The full key and a ready-to-paste Cursor MCP config are shown once. Store them securely.

Agent keys are shown only once at creation. If you lose a key, revoke it and create a new one.

Cursor MCP configuration (production)

Paste into ~/.cursor/mcp.json or .cursor/mcp.json in your repo:

{
  "mcpServers": {
    "visualq": {
      "command": "npx",
      "args": ["-y", "@visualq/mcp"],
      "env": {
        "VISUALQ_API_KEY": "vq_org_live_YOUR_KEY_HERE",
        "VISUALQ_BASE_URL": "https://visualq.ai",
        "VISUALQ_DEFAULT_PROJECT": "your-project-slug"
      }
    }
  }
}

Restart Cursor. The visualq server should expose 90+ tools (list_my_tools).

VISUALQ_DEFAULT_PROJECT is optional — omit it if you work across many projects and pass "project": "slug" on each call.

Local development

Point at your dev server while running npm run dev in the VisualQ repo:

"VISUALQ_BASE_URL": "http://localhost:3000"

Project resolution

Situation	Behavior
Org key + `project` arg	Resolves any project in the org
Org key + no `project` + default on key	Uses `defaultProject` / `VISUALQ_DEFAULT_PROJECT`
Org key + no `project` + no default	Error: `project is required with org agent keys`
Project key + no `project`	Uses the bound project
Project key + wrong `project`	`403`

Verify the connection

Ask your agent to run:

get_project with { "project": "your-slug" }
list_scenarios with { "project": "your-slug" }
check_setup_health with { "project": "your-slug" }

Or select the MCP prompt setup-health-review.

Common agent workflows

Goal	Tools
Onboard a new client site	`create_project` → `crawl_site` → `create_scenario` → `run_baseline`
FRT from Gherkin	`frt_save_feature_draft` (`name`, `gherkin`, `confirm: true`) → `frt_compile_feature` → `run_frt_feature`
Pre-merge VRT	`run_vrt` (project CI key or dashboard) → `get_run_failures` → `explain_vrt_failure`
Jira-driven QA	Name scenarios/features with ticket ids; link in descriptions

Mutations require "confirm": true in tool arguments.

Security

Store keys in password manager or IDE secrets — never commit to git
Use mcp_read for read-only diagnostics when write access is not needed
Revoke unused keys from Settings → Agent API Keys

Troubleshooting

Symptom	Fix
`project_resolution_error`	Pass `"project": "slug"` or set default project on the key / `VISUALQ_DEFAULT_PROJECT`
`confirm_required`	Add `"confirm": true` to mutating tools
`403` on `/api/ci/*` with org key	Expected — use a project CI key for pipelines
MCP `fetch failed` in Cursor	Check `VISUALQ_BASE_URL` is `https://visualq.ai` (not `localhost`) and restart Cursor
FRT compiles but no video on card	Run the feature with `run_frt_feature`; video is uploaded by the worker after a run