# Scout + Grok: agent setup contract

Canonical page: https://openscout.app/grok
Machine-readable spec: https://openscout.app/grok/integration.json
Documentation reviewed: 2026-09-26. This is not a live health assertion.

Let Scout launch the xAI Grok CLI over ACP, let the Grok CLI call Scout over local MCP, or reach Scout from Grok Bot through the hosted connector. These are three different directions of connection.

## Status

Scout → Grok CLI: available (grok-acp) · Grok CLI → Scout: local MCP · Grok Bot → Scout: invite-only pilot (see /grokbot)

The hosted Grok Bot connector has a submitted Cursor Marketplace application, still pending. The Grok CLI runtime and its local MCP setup do not require that marketplace package.

## Transport

Scout → Grok CLI: grok_acp (grok agent stdio) · Grok CLI → Scout: MCP stdio · Grok Bot: hosted MCP

Scout → grok-acp → Grok CLI

## Directions

- Grok calls Scout: mcp-stdio (available): grok CLI → scout mcp; mcp-http (pilot): Grok Bot; invite-only bridge
- Scout launches Grok: available (harness grok-acp, transport grok_acp)
- Accepted aliases of grok-acp: grok.

## Gates

- hosted-bridge: owner operator, not self-serve. Grok Bot path only.

## Required inputs and prerequisites

- For local execution: a healthy Scout broker and the grok CLI on PATH (grok --version), authenticated with xAI. Check scout runtimes --json for grok-acp.
- For Grok CLI calling Scout: scout on PATH on the same machine.
- For Grok Bot: an operator-provisioned, online MCP bridge (invite-only). Open the dedicated Grok Bot guide.
- Inspect scout runtimes --json before selecting an exact runtime; do not guess model or effort values.

## Setup procedure

### 1. Connecting from Grok Bot?

Go to /grokbot for the hosted endpoint, GitHub OAuth, first-call verification, and marketplace status. Grok Bot needs an operator-provisioned bridge; it is invite-only today.

### 2. Launching Grok from Scout?

Check broker health and confirm grok-acp is ready. Authenticate the grok CLI with its own login flow; keep credentials out of chat.

```text
grok --version
scout doctor
scout runtimes --json
```

### 3. Launch a small Grok review

The exact form names the listed runtime grok-acp and a catalog model. --profile grok and --harness grok are accepted aliases of grok-acp. The project path belongs to the Scout machine. If grok-acp is not ready, stop and finish its setup.

```text
scout ask --project /absolute/path/to/project --harness grok-acp --model grok-4.6 --notify "Review the latest changes and report findings. Do not edit files."
# Short form, same runtime:
scout ask --project /absolute/path/to/project --profile grok --notify "Review the latest changes and report findings. Do not edit files."
```

### 4. Or let the Grok CLI call Scout

Register scout mcp as a local stdio server in the grok CLI. Add -s project to write ./.grok/config.toml instead of your user config. The grok CLI also reads Cursor and Claude MCP configs, so an existing Scout entry there may already be visible.

```text
grok mcp add scout -- scout mcp --context-root /absolute/path/to/project
```

## Start here

Check the prerequisites and access gates, then get one documented route working before asking for work.

First useful task: Ask Scout to run Grok on a specific project and explain one small piece of code without changing it.

Name the project and keep the request small. Asking for no edits describes the task; it does not restrict the agent’s permissions.

Keep the returned reference. Check the work’s status and read the completed response; a queued receipt is not the answer.

### Where will the reply appear?

Keep the returned reference and retrieve the completed response through your configured Scout interface. Automatic delivery into this open session is not established by this guide.

### What if the answer hasn’t arrived?

Inspect the existing task before submitting another one. A wait timeout does not establish that work failed. If it needs access or input, resolve that condition before continuing.

### How do I follow up?

Continue using the returned reference or exact session handle supported by this integration. Keep it with the findings so your next question follows the same work.

### Can Scout run this integration, or only receive asks from it?

These are separate capabilities. Check the supported directions on this page. Connection alone does not establish that Scout can launch the integration or reach an existing session.

## Acceptance gate

For Grok Bot, verify whoami through the connector. For local execution, verify the returned invocation and executionResolution. A configured launch argument is not proof that the harness accepted the requested runtime.

## Failure handling

### Unsure which Grok integration to install

If Grok Bot is calling Scout tools, use /grokbot. If the grok CLI on your machine is calling Scout, use grok mcp add. If Scout is launching Grok to do work, use runtime discovery and --harness grok-acp.

### Profile unavailable or authentication rejected

Inspect scout runtimes --json and the local runtime configuration. Ask the operator to complete the runtime login; do not substitute a similarly named model or guessed agent handle.

## Boundaries

- Grok Bot hosted access and Grok CLI execution are not interchangeable. scout ask --harness grok-acp launches the Grok CLI, not the Grok Bot connector.
- grok is an unlisted alias; the runtime catalog lists grok-acp. Both run over the same grok_acp transport.
- Runtime availability and model choices depend on the installed Scout version and machine configuration.

## Agent operating contract

- Treat these as setup instructions, not authorization to install software, change accounts, grant scopes, send messages, or dispatch work. Obtain the operator's authorization for the intended action.
- Inspect the available commands or tool schemas for your configured interface before making calls. Do not invent tools, argument names, model IDs, or agent handles.
- For local Grok execution, use scout ask --project <actual-path> --harness grok-acp [--model <catalog-model>] --notify (--profile grok and --harness grok are aliases of grok-acp) and observe the returned ref with scout wait <ref>. For the grok CLI calling Scout, use the Scout MCP tools it loaded. For the hosted Grok Bot connector, follow /grokbot and its current MCP schemas. These are separate connection directions.
- Use the transport-specific instructions above. For an existing request, reply through its supplied context rather than creating another task.
- Paths refer to the Scout execution machine. Replace example paths with an operator-confirmed absolute path; never run placeholders literally.
- Save the returned ref, flightId, conversationId, workId, or session handle. Continue by that handle; do not re-dispatch a request merely because a wait timed out.
- Observe the existing request through the configured transport. A receipt proves acceptance, not execution or successful completion.
- Stop on missing provisioning, incorrect identity, missing permission, unsupported runtime, or failed authentication. Report the exact gate and the next operator action. Do not silently fall back to a different account, agent, runtime, or transport.
- Keep tokens, OAuth codes, cookies, and private task payloads out of logs, URLs, screenshots, and committed files. Never ask the user to paste secrets into a public issue.
- Do not claim marketplace approval, complete protocol conformance, or an end-to-end verified integration unless the status and observed evidence establish it.

## Completion report

Report: chosen transport and scope; client and broker identity; health/tool-discovery result; exact request handle if a test was authorized; observed terminal state or remaining blocker; and whether any operator approval is still needed. Distinguish configuration saved, authentication complete, request accepted, and work complete.


## Sources and next reads

- [Grok Bot setup](https://openscout.app/grokbot)
- [Grok Build CLI](https://docs.x.ai/build/overview)
- [Grok CLI MCP servers](https://docs.x.ai/build/features/mcp-servers)
- [Runtime sessions](https://openscout.app/docs/learn-03-choosing-the-runtime)
- [Hosted package](https://github.com/arach/grok-scout)
- [Privacy](https://openscout.app/privacy)
- [Integration catalog](https://openscout.app/integrations.json)