Connect Grok Bot to AQ and Ship Code on Your Repositories

Published October 27, 2026 · by the AQ team

Connect Grok Bot to AQ's hosted MCP server, and your Bot can turn a request into work on a real team repository: it creates an AQ workspace, launches the coding CLI you choose in an isolated worktree on your team's machine, and returns the pull request and preview. Teammates can open the same live workspace while the run is underway, inspect the diff, comment on lines, and merge through the repository's normal review path. On its own, Grok Bot already works from a persistent cloud computer with a browser, command line, files, and connectors; xAI also documents Cloud Agent delegation, but its Grok Bot docs do not describe AQ's shared coding workspace and review flow.

What Grok Bot can do by itself

As of October 27, 2026, xAI describes Grok Bot as working from a persistent cloud computer. It can use a browser, command line, files, and connected tools while your laptop is closed. Every Bot on one account shares that user's computer, including its files, browser sessions, and command-line credentials. The screens are separate work surfaces, but xAI is explicit that they are not separate security boundaries.

For coding, xAI says Grok Bot can operate development environments and can delegate coding tasks to separate computers through Cursor Cloud Agent controls. Cursor manages Grok Bot's model selection, and xAI's security page says there is no customer-facing model picker. Grok Bot can also use a GitHub connector for repositories, issues, pull requests, and code. These are real coding capabilities. The cited documentation does not specify one standard path from a Grok Bot request to a team-visible live coding session, a reviewed diff, and a merged pull request.

Access follows the signed-in person. A Bot starts with no accounts of its own, uses only the applications and connectors that the person or team grants, and hands login and verification steps back to the person. Auto Review can allow, deny, or pause risky actions for approval. Those controls still matter after AQ is connected because the Bot is deciding when to call AQ tools.

What changes when Grok Bot can use AQ

The connector turns Grok Bot into a dispatcher for a shared coding system. Grok keeps the request and orchestration conversation. AQ owns the repository workspace, the selected coding-agent run, the team review surface, and the resulting pull request.

This separation is useful when the model and the coding harness should be chosen independently. Grok Bot can remain the standing agent that receives the request, while AQ sends the implementation to the CLI that fits the repository or the team's available subscriptions. For the distinction between models and coding harnesses, see Grok 4.7 for coding agents. For the protocol layer, see MCP servers for coding agents.

Connect Grok Bot to AQ, step by step

You need an AQ Pro account, a repository connected to AQ, and Grok Bot access. AQ's MCP endpoint is already reachable on the public internet, which satisfies xAI's requirement for custom MCP connectors. No tunnel or local MCP process is needed.

1. Open Grok connectors. Go to grok.com/connectors, choose New Connector, then choose Custom.
2. Add AQ. Enter a recognizable name such as AQ and use https://aq.dev/mcp as the MCP server URL. AQ uses Streamable HTTP.
3. Sign in to AQ. Complete the browser sign-in and consent screen. The OAuth grant acts as the AQ person who approves it. AQ also supports API keys sent as Bearer headers for headless clients, but xAI's custom-connector instructions do not document a Bearer-header field. Use OAuth in Grok Bot.
4. Make the connector available to the Bot. Return to Grok Bot and enable AQ under its connected apps if it is not already available. xAI says Grok discovers the custom server's tools and makes them available in conversations.
5. Verify with a read. Ask Grok Bot: Call AQ's list_workspaces tool and show the five most recently updated workspaces. The call is read-only and verifies the transport, sign-in, and visible scope without changing a repository.

Business and Enterprise setup

On Grok Business and Enterprise, a team admin provisions the connector first. In console.x.ai, select the team, go to Grok Business → Connectors, choose + Add Connector, select Other, and enter https://aq.dev/mcp. Team members can then connect their own AQ accounts from grok.com/connectors.

Enterprise has two additional checks. Grok Bot inherits the team's connector policy, including the Enterprise MCP allowlist. If the team uses a destination allowlist and turns on Apply to MCP servers under Network, the AQ MCP host must also be allowed. Add aq.dev to the permitted destinations before testing the connector. xAI notes that this network switch is off by default.

The current AQ tool names

These are the exact tool names in AQ's hosted MCP definition on October 27, 2026. Identity and read tools are whoami, list_workspaces, count_workspaces, get_workspace, get_workspace_events, list_workspace_prs, get_preview_url, list_agent_sessions, get_agent_run, delegation_status, list_connections, list_repos, and list_webhooks. Workspace and run tools are create_workspace, close_workspace, reopen_workspace, update_workspace, share_workspace, start_agent, send_agent_message, stop_agent, delegate, and archive_agent_session. Webhook writes are create_webhook and delete_webhook. The OAuth grant can expose a smaller set, so Grok Bot should use the tools it actually discovers instead of assuming every name is enabled.

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

The sequence below was checked on October 27, 2026 against AQ's live OpenAPI 3.1 document and the MCP tool definitions. The OpenAPI body for workspace creation accepts title, description, repo_id, and base_branch. Starting a run requires message and source, with native harness, model, and connection fields when a connected CLI should do the work. The MCP tools map REST path IDs to workspace_id and agent_session_id. Mutating MCP tools also accept an optional idempotency_key, the tool form of the REST Idempotency-Key header.

Before this five-call path, use list_repos once to get the repository ID. If you want a connected CLI rather than AQ credits, call list_connections and copy the desired connection ID. The example uses Codex, but the returned connection list is the source of truth for the approving person.

1. Create one workspace for the task

create_workspace
{
  "title": "Fix the flaky test in repo X",
  "description": "Reproduce the flaky test, fix the cause, run the focused and relevant test suites, commit the change, push the branch, and open a pull request.",
  "repo_id": "repo_...",
  "base_branch": "main",
  "idempotency_key": "grok-flaky-test-workspace-1"
}

Keep workspace.id from the result. AQ creates a branch and isolated worktree for this work item.

2. Start the selected coding CLI

start_agent
{
  "workspace_id": "<workspace.id>",
  "message": "Find the flaky test, reproduce it before changing code, fix the underlying cause, run the focused test repeatedly and the relevant suite, then commit, push, and open a pull request with the evidence in its description.",
  "source": "native",
  "native_harness": "codex",
  "native_model_id": "default",
  "native_connection_id": "<connection.id>",
  "idempotency_key": "grok-flaky-test-agent-1"
}

Keep agent_session.id. To use AQ credits instead, set source to aq and omit the native fields; a named AQ model is optional through model_selection_id. The source must be chosen explicitly so an integration cannot move from a connected subscription to billed AQ credits by accident.

3. Poll the run

get_agent_run
{
  "agent_session_id": "<agent_session.id>"
}

Poll until agent_session.status is completed, failed, or cancelled. If it becomes waiting_for_user, show the question to the person instead of pretending the run finished. The response includes the transcript tail and recent progress events, so Grok Bot can summarize evidence without inventing a terminal transcript.

4. Read the pull request

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

Return the pr_url and state from the result. An empty list is a real outcome: it means AQ is not tracking a pull request for that workspace yet. Do not report that a pull request exists just because the prompt asked for one.

5. Read the preview

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

Return a running preview URL when one exists. Some repositories have no dev-server preview, and a stopped or failed preview can return no usable URL. The workspace, agent run, pull request, and preview are separate results, which makes partial success visible.

Instruction text to paste into Grok Bot

Use AQ's MCP server at https://aq.dev/mcp for coding work on my repositories.
Before changing anything, use list_repos to identify the repository and
list_connections to identify the coding CLI account I name. Create one AQ
workspace for each task, then start_agent with that connected CLI. Poll
get_agent_run and stop if it needs my input. When the run ends, call
list_workspace_prs and get_preview_url. Give me the AQ workspace ID, run
status, pull request URL and state, preview URL if one exists, and the test
evidence from the run. Never claim a PR or preview exists when the tool returns
none. Do not merge, close, delete, or change workspace sharing unless I ask.

Permissions and safety

The AQ connection acts as the person who approved it. It sees only that person's teams and workspaces, and AQ re-checks live membership and access on every request. The MCP server advertises only tools allowed by the grant's scopes, so a read-only connection cannot create a workspace or start a run. Review the scope list on AQ's consent screen before approving.

AQ marks read-only and destructive tools for compatible clients. Destructive operations require an explicit confirmation argument, such as confirm=true when closing a workspace. Mutating tools accept idempotency keys so a retry with the same arguments returns the original result instead of creating duplicate work. Read the full permission and retry behavior in the AQ API guide.

Revoke the connection from AQ Settings → Connections → API keys. OAuth connections are named MCP: <client>, and revocation disconnects the client immediately. On the Grok side, xAI says connector tokens stay on its connector backend and the model sees tool results rather than OAuth tokens. Keep Grok Bot's Auto Review enabled, use narrow Ask first rules for consequential actions, and put the stop conditions in the request itself.

Limits and caveats

• AQ Pro is required. API keys, the public API, webhooks, and the hosted MCP server are part of the AQ Pro plan.
• The repository and coding account must already work in AQ. The connector does not create GitHub access or sign a CLI into its vendor account. Use list_repos and list_connections before dispatch.
• A pull request and preview are outcomes, not guarantees. A run can fail, wait for input, finish without opening a pull request, or work in a repository without a preview command.
• Grok Bot's shared coding-session behavior is not documented. xAI documents Team Bots, connected apps, hosted computers, approvals, and Cloud Agent delegation. The cited pages do not document teammates joining the same live development session, reviewing its diff in Grok Bot, or merging from it.
• Use OAuth for the Grok connector. xAI says custom MCP servers may authenticate with OAuth or API keys, but does not document an arbitrary Bearer-header control in the Grok custom-connector steps. AQ's Bearer option is for headless clients that expose that configuration.
• xAI Remote MCP Tools are a different product surface. The Remote MCP Tools API adds an MCP server to an xAI API request through its tools array. It is not the Grok Bot connector configured at grok.com/connectors, and it is not needed for this guide.

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.

In this workflow, Grok Bot is another way into those same team workspaces. A person can ask a standing Bot for the change, Grok dispatches it through the same MCP tools any compatible agent can use, and the chosen coding CLI works in the repository and environment the team already shares. The handoff does not trap the task inside Grok Bot's own computer or model choice. AQ keeps the worktree, run, review evidence, and pull request in one place that teammates can enter.

That is the practical link between every agent working with the team, cloud workspaces, and human review. Grok Bot handles intake and follow-through. AQ gives the coding run a real repository, durable compute, visible execution, and a review path before merge.