How to connect your OpenAI dot to AQ

Published October 27, 2026 · by the AQ team

Connect an OpenAI dot to AQ and it can file a work item on one of your team's real repositories, start the coding agent your team chose in an isolated git worktree on the team's machine, and return a live workspace, preview, and pull request for teammates to review. The team can watch the same session, inspect the diff, comment on lines, and merge from AQ. A dot can also create Codex tasks without AQ, as OpenAI documents; our OpenAI dots explainer covers that model, while this guide stays on the AQ connection and workflow. As of October 27, 2026, the complete write workflow requires a ChatGPT Business or Enterprise/Edu workspace because ChatGPT Pro custom MCP connections are limited to read and fetch tools.

How a dot codes on its own

OpenAI's current getting-started documentation says a dot can create cloud tasks in Codex cloud environments. You create the Codex environment first, including the repository setup available to that environment, and then ask the dot to use it. The dot owner can open the task from the dot's activity and review the result.

A dot can also create Work or Codex tasks on a computer you connect through the ChatGPT desktop app. Local access starts off, requires two confirmations, and works only while that computer is online with the app open. OpenAI documents Codex for this coding path. It does not document a picker for other coding agents in the dot's own coding workflow. For the Codex task and dashboard side of the handoff, see Codex background agents and the agents dashboard.

What changes when your dot can use AQ

The dot remains the coordinator. AQ supplies the repository workspace, the team's chosen coding agent, and the shared review surface.

Connect AQ from Plugins

These are the current steps in OpenAI's custom MCP server guide and plugin connection guide, checked on October 27, 2026. Use ChatGPT on the web for the custom MCP setup.

1. Check the account and workspace. Full custom MCP support is available to Business and Enterprise/Edu. In Business, only admins and owners can create and publish the connection. In Enterprise/Edu, admins and owners can create and test it, and an admin can grant selected members the Create plugins with MCPs permission through RBAC. Only admins and owners can publish it. Pro can connect custom MCP servers with read and fetch permissions, which does not permit the write sequence below.
2. Open Plugins. Select the plus button, then Add custom MCP server. Developer Mode is not required in this current flow.
3. Name the connection. Enter AQ and, optionally, a description such as Create and review coding work in our AQ repositories.
4. Enter the endpoint. Under Connection, use the public HTTPS MCP endpoint https://aq.dev/mcp. AQ serves streamable HTTP from that address.
5. Configure authentication. Choose OAuth. Sign in to AQ in the browser window and approve the AQ consent screen. The connection acts as the AQ person who approves it.
6. Accept the warning. Review OpenAI's risk warning, select I understand and want to continue, then select Create as a plugin. Review the discovered tools and metadata before installing it.
7. Verify it. Start a new conversation, type @, select AQ, and ask it to call list_workspaces. That read-only tool should return the AQ workspaces visible to the connected person. OpenAI says plugin permissions are shared across dots, ChatGPT, ChatGPT Work, and Codex, so the installed connection is available to the dot within the permissions you granted.

AQ's shorter client-focused instructions live at AQ MCP setup. If the tool list later changes, OpenAI says a workspace admin must refresh and review the connection because approved custom MCP tools are kept as a frozen snapshot.

Worked example: fix a flaky test and open a pull request

Give the dot the outcome, repository, agent choice, and review requirements in one instruction. This version adapts the direct-agent prompt in the AQ MCP documentation:

Use the AQ plugin for this work. In repository X, create a work item named
"Fix the flaky checkout test." Run the coding agent from my connected
<team-selected agent> account. Reproduce the failure, fix its cause, add or
update a regression test, run the focused test and the relevant full suite,
review the diff, commit and push the branch, and open a pull request.
Poll the AQ run until it finishes or needs my input. Then give me the AQ
workspace, preview URL if one is running, test results, and pull request URL.

The dot can discover the repository id with list_repos and the available agent accounts with list_connections. It then uses this sequence. The argument names below match AQ's live OpenAPI document and MCP definitions checked on October 27, 2026.

1. Create the work item

create_workspace
{
  "title": "Fix the flaky checkout test",
  "description": "Reproduce the flaky checkout test, fix the cause, add a regression test, run the relevant suite, and open a pull request.",
  "repo_id": "<repo-id-for-repository-X>",
  "base_branch": "main",
  "idempotency_key": "dot-flaky-checkout-create-1"
}

Save workspace.id from the result. The work item now has its own branch and isolated worktree.

2. Start the chosen coding agent

start_agent
{
  "workspace_id": "<workspace-id>",
  "message": "Reproduce the flaky checkout test, fix the underlying cause, add or update a regression test, run the focused test and relevant full suite, review the diff, commit and push the branch, and open a pull request. Report the commands and results. Stop and ask if repository behavior or product intent is ambiguous.",
  "source": "native",
  "native_harness": "<harness-from-list_connections>",
  "native_connection_id": "<connection-id-from-list_connections>",
  "idempotency_key": "dot-flaky-checkout-run-1"
}

source: "native" runs the person's connected coding-agent subscription. To use AQ credits, choose source: "aq" and omit the native fields. Save agent_session.id. Starting the agent does not automatically push or open a pull request, so the message asks the coding agent to do both.

3. Poll the run

get_agent_run
{
  "agent_session_id": "<agent-session-id>"
}

Repeat while the status is queued or running. If it becomes waiting_for_user, show the question to the person and continue the same conversation with send_agent_message. Stop polling when the status is completed, failed, or cancelled.

4. Read the pull request and preview

list_workspace_prs
{
  "workspace_id": "<workspace-id>"
}

get_preview_url
{
  "workspace_id": "<workspace-id>"
}

list_workspace_prs returns pull requests AQ has tracked for the workspace. get_preview_url returns any running dev-server previews; an empty list means no preview is running. The dot reports those results, while teammates can open the same AQ workspace and review the session and diff. The dot's own OpenAI approval rules still apply to every plugin action it takes.

Permissions and safety

An AQ MCP connection acts as the person who approved it. It sees only workspaces and teams that person can access, and AQ checks current membership on every request. The server advertises only tools allowed by the connection's scopes. Read tools such as list_workspaces, get_agent_run, list_workspace_prs, and get_preview_url are marked read-only. AQ's explicitly destructive close_workspace and delete_webhook tools require confirm=true. Mutating tools accept an idempotency_key, so a retry with the same key and arguments replays the first result instead of doing the work twice. The complete permission and API contract is in the AQ API documentation.

You can revoke the connection from AQ Settings → Connections → API keys; OAuth entries are named MCP: <client>. On OpenAI's side, dot plugin permissions and action rules remain in force. OpenAI says plugin permissions are shared with the dot, Custom Rules can add boundaries but cannot remove core safeguards, and sensitive actions may require confirmation or a handoff. A dot can make mistakes even when it follows those rules, so review consequential code and repository actions.

Limits and caveats

• AQ plan. The hosted MCP server, public API, and webhooks are part of the AQ Pro plan. As of October 27, 2026, early-access pricing is $50 per user per month, with $10 of AQ agent credits per seat. Runs on a person's connected Claude, OpenAI, Cursor, or other subscription are not marked up by AQ.
• OpenAI plan. OpenAI's dot page says dots are rolling out to Pro users aged 18 and older outside the European Economic Area, Switzerland, and the UK; to eligible Business Premium users in supported regions; and as an admin-enabled beta for Enterprise, including Edu and Healthcare. Its MCP page says full MCP is currently available to Business and Enterprise/Edu, while Pro custom servers are limited to read and fetch permissions.
• Web setup. OpenAI currently supports adding custom MCP servers on ChatGPT web, not mobile. Business admins and owners create and publish them. Enterprise/Edu can grant connection creation through RBAC, while publishing remains admin or owner controlled.
• Tool refresh. ChatGPT keeps a frozen snapshot of a custom server's approved tools and inputs. AQ tool changes do not appear until an authorized workspace administrator refreshes and reviews the app.
• Not documented by OpenAI. The reviewed dot documentation does not specify teammate access to the owner's live coding task, a non-Codex agent picker for the dot's own coding route, dot-specific MCP polling or retry limits, or how long a Codex cloud task environment is retained. The comparison above labels those points as not documented.

Where AQ fits

AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. The dot handles the conversation and dispatch. AQ gives that request an isolated worktree on the team's machine, runs the agent and account the team selected, keeps the work visible, and carries the result through review and merge. That is the practical role of AQ in an every-agent-together workflow: the dot can keep coordinating while the engineering team retains the live workspace and review path.