Connect your AI agent to AQ over MCP

Published October 14, 2026 · by the AQ team

AQ's hosted MCP server lives at https://aq.dev/mcp. Add that one URL to any MCP-compatible client (as of October 2026 that includes Claude Code, Claude and ChatGPT connectors, Cursor, and others), approve the browser sign-in once, and the agent can list and create AQ workspaces, start and steer AQ Composer conversations, and read events, pull requests, and preview URLs, all as you, with your permissions. There is nothing to install and no key to copy for OAuth-capable clients.

Connect in one step

Claude Code (one command, then approve the sign-in it opens):

claude mcp add --transport http aq https://aq.dev/mcp

Claude or ChatGPT connectors: add a custom connector with the URL https://aq.dev/mcp. The browser opens AQ's sign-in and consent screen; approve, and the tools appear in the conversation.

Cursor and other JSON-configured clients:

{
  "mcpServers": {
    "aq": {
      "url": "https://aq.dev/mcp"
    }
  }
}

Headless clients that cannot run a browser flow authenticate with an API key from the AQ API instead, sent as a Bearer header:

{
  "mcpServers": {
    "aq": {
      "url": "https://aq.dev/mcp",
      "headers": { "Authorization": "Bearer aq_your_key" }
    }
  }
}

Each connected app appears in Settings → Connections → API keys (OAuth connections are named MCP: <client>). Revoking the entry disconnects the app immediately.

Or just tell your agent

If your coding agent manages its own MCP configuration, paste this:

Connect to AQ's MCP server at https://aq.dev/mcp (streamable HTTP, OAuth).
Then use its tools to create a workspace on my repository and start an
AQ Composer run with my task. Poll get_agent_run for progress and give me
the workspace link and any pull request it opens.

What a connected agent can do

• Work with workspaces: list_workspaces and count_workspaces (with status, repo, and text filters), get_workspace, create_workspace (optionally from a base branch), update_workspace, share_workspace, close_workspace, reopen_workspace, list_repos, and whoami to identify the connection. Every workspace is an isolated git worktree on your own infrastructure.
• Run the built-in agent: start_agent starts an AQ Composer conversation in a workspace, send_agent_message steers it mid-run, get_agent_run reads status and the transcript tail, stop_agent stops the current turn, list_agent_sessions and archive_agent_session manage the conversations. list_connections names your connected CLI accounts for runs on your own subscription.
• Read the results: get_workspace_events for activity, list_workspace_prs for pull requests the work produced, get_preview_url for the running app preview.
• React to events: list_webhooks, create_webhook, and delete_webhook manage signed outbound webhooks so your own service hears about workspace and agent activity without polling.

The server only advertises the tools the connection's scopes allow, so a read-only connection cannot create or close anything, and it annotates read-only versus destructive tools so clients can gate confirmations. Destructive operations ask for explicit confirmation arguments (closing a workspace requires confirm=true), and mutating tools take an optional idempotency_key argument that makes automatic retries safe: a repeat with the same key and arguments replays the first result instead of executing twice.

Permissions and safety

An MCP connection acts as the person who approved it: it sees only that person's workspaces and teams, and access is re-checked on every request against live membership. Internal identifiers, file paths, credentials, and infrastructure details never appear in tool results. For scope details, pagination, idempotent writes, webhooks, and the complete REST surface, read the AQ API documentation; the machine-readable contract is the OpenAPI document at /v1/openapi.json.

Verify the connection

Ask the connected agent to call list_workspaces. It is read-only, returns your visible workspaces, and proves authentication, scopes, and transport in one call. From a shell, the equivalent is:

curl -fsS https://aq.dev/mcp \
  -H "Authorization: Bearer aq_your_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'