# Scout + MCP: agent setup contract

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

Connect an MCP client to Scout locally over stdio or remotely through the hosted HTTP gateway. Discover agents, ask for work, and follow durable results.

## Status

Local stdio: available · Hosted HTTP: pilot (connect your Mac with scout mesh bridge connect)

MCP is the connection protocol. Marketplace packages simplify installation in a particular client; they do not install your broker, provision a bridge, or authorize access by themselves.

## Transport

Local stdio · hosted Streamable HTTP + OAuth

MCP client → Scout tools → Local broker

## Directions

- MCP calls Scout: mcp-stdio (available); mcp-http (pilot): Needs this Mac's bridge connected: scout mesh bridge connect
- Scout launches MCP: not supported. MCP is a host door, not a harness.

## Gates

- hosted-bridge: owner user. Hosted HTTP only; local stdio has no gate.

## Required inputs and prerequisites

- For local stdio: OpenScout installed, scout on PATH, and a healthy broker on the same machine.
- For hosted HTTP: a healthy Scout broker plus this Mac's bridge connected to your GitHub account. Run scout mesh bridge connect on the Scout machine, sign in, and approve. Each account reaches only the bridges it connected.
- For hosted HTTP: the Scout machine and bridge must stay online. Adding the server to a client does not install Scout or connect a bridge.

## Setup procedure

### 1. Which transport?

Same machine as Scout → stdio. Anything else → hosted HTTP, after you connect the Scout machine's bridge to your GitHub account. Without a connected bridge, https://mcp.oscout.net authenticates and then returns node_unreachable. OAuth in the client does not connect a bridge.

### 2. Choose your transport

For a client on the Scout machine, launch scout mcp as a stdio process. For a remote or hosted client, connect the bridge first, then configure https://mcp.oscout.net as a Streamable HTTP endpoint with OAuth.

### 3. Configure local stdio

Merge a server entry into your client’s MCP configuration. Replace the absolute project path; preserve existing servers. The client owns the subprocess lifecycle.

```text
{
  "mcpServers": {
    "scout": {
      "command": "scout",
      "args": [
        "mcp",
        "--context-root",
        "/absolute/path/to/project"
      ]
    }
  }
}
```

### 4. Or let Scout write the local entry

For Claude Code and Codex, scout mcp install writes the stdio entry for you. Preview with --dry-run first; add --force to replace a non-matching scout entry.

```text
scout mcp install --host claude --dry-run
scout mcp install --host codex --dry-run
```

### 5. Connect this Mac for hosted HTTP

On the Scout machine, run this once. It opens your browser; sign in with GitHub and approve. The bridge gets its own credential for your account, stored in the keychain, and runs under the Scout service. scout mesh bridge disconnect revokes it.

```text
scout mesh bridge connect
scout mesh bridge status
```

### 6. Or configure hosted HTTP

With the bridge connected, use this server entry if your client accepts mcpServers JSON. In form-based clients enter the URL, choose HTTP and OAuth, then save and connect. Leave custom headers empty. In Claude, open Settings → Connectors, add a custom connector with the URL, and leave the OAuth client fields empty.

```text
{
  "mcpServers": {
    "scout": {
      "url": "https://mcp.oscout.net"
    }
  }
}
```

### 7. Verify identity and request work

List the tools and call whoami first. For new work, use ask with projectPath, optional harness, and replyMode notify. Use the returned handles to observe completion.

```text
{"projectPath":"/absolute/path/on/scout-machine","harness":"claude","body":"Review the latest changes and report findings. Do not edit files.","replyMode":"notify"}
```

## Start here

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

First useful task: Discover the connected Scout tools, check your identity, then submit one small ask and inspect the returned flight until it finishes.

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

Confirm tool discovery and the intended whoami identity. Submit one small, authorized ask and retrieve its result through invocations_get or invocations_wait. A transport handshake or OAuth approval alone is not an end-to-end check.

## Failure handling

### node_unreachable

On the Scout machine run scout mesh bridge status. If it is not configured, run scout mesh bridge connect and approve with the same GitHub account you use in the client. Repeated OAuth attempts in the client will not connect a bridge.

### quota_exceeded (HTTP 429)

Your account has used its daily tool calls. The response says when the limit resets (midnight UTC). Handshakes and tool listings stay available.

### OAuth fails or the wrong identity appears

Check the signed-in GitHub account and connector authorization. Reconnect to the intended account before running tools. Never paste tokens into a chat.

### No tools appear

Save the MCP configuration, reconnect, and refresh the client tool list. Confirm HTTP transport and the exact endpoint; do not substitute a local stdio command in a remote client.

### Local stdio emits startup errors

Run scout doctor outside the MCP transport, verify scout on PATH, and check the absolute context-root. Do not write human-readable diagnostics to the MCP stdout stream.

## Boundaries

- Hosted access requires an online bridge connected to the same account: scout mesh bridge connect, then scout mesh bridge status. Each self-serve account gets 1,000 tool calls per UTC day; handshakes and tool listings are not counted.
- Auth posture (hosted): an unauthenticated request returns 401 with WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp", scope="mcp:core". The authorization server publishes RFC 8414 metadata with PKCE S256, the iss response parameter, client ID metadata documents, and a dynamic client registration endpoint, so clients that do CIMD or DCR need no pre-registered client ID.
- Protocol revision: Scout's MCP server is built on the TypeScript MCP SDK 1.29 and negotiates up to revision 2025-11-25. It does not implement the stateless 2026-07-28 revision.
- Core scope is mcp:core. Discover the actual tool schemas; do not assume advanced/pro-tier operations are enabled.
- Tool inputs/results can contain messages, project paths, instructions, and agent output and pass through the client, gateway, and bridge.

## Capabilities

The hosted endpoint https://mcp.oscout.net serves Scout's mcp:core tier, and local stdio serves the same tools plus operator-only extras. Every tool declares a title and a read-only or write annotation. Read-only tools only return data from your own Scout broker. Write tools create messages, asks, and work updates in that broker, and feedback_send reports a problem to the OpenScout team.

| Tool | Access | What it does |
|---|---|---|
| `whoami` | read-only | Show the Scout identity and broker this connection acts as. |
| `agents_search` | read-only | Find agents on the mesh that can take a request. |
| `agents_resolve` | read-only | Resolve one agent handle, or report why it is ambiguous. |
| `ask` | write | Ask an agent to answer, review, or build something, and get a handle to follow. |
| `invocations_get` | read-only | Read the current state of an ask. |
| `invocations_wait` | read-only | Wait briefly for an ask to finish and return its state. |
| `messages_send` | write | Send a direct message or a channel post. |
| `messages_reply` | write | Reply inside an existing conversation. |
| `messages_inbox` | read-only | Read recent messages addressed to this identity. |
| `messages_channel` | read-only | Read recent messages in a named channel. |
| `current_reply_context` | read-only | Check whether a reply would continue an inbound ask. |
| `broker_feed` | read-only | Read one agent's messages, deliveries, and errors in one view. |
| `tail_events` | read-only | Read recent activity from the coding agents on the Scout machine. |
| `labels_brief` | read-only | Summarize the records that share a label. |
| `labels_feed` | read-only | Read the event backlog for a label. |
| `work_update` | write | Move a work item through progress, review, and done. |
| `notify_operator` | write | Send the human operator a non-blocking note. |
| `consult_operator` | write | Ask the operator for advice while continuing with a stated default. |
| `feedback_send` | write | Report a bug or rough edge in Scout to the OpenScout team. |
| `sessions_attach` | write | Give this conversation a Scout mailbox so agents can reply to it. |
| `sessions_get` | read-only | Read the mailbox attached to this conversation. |
| `sessions_poll` | read-only | Read pending items in the attached mailbox. |
| `sessions_ack` | write | Mark a mailbox item as received. |
| `sessions_reply` | write | Send the final answer for a delivered task. |

## 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 requested work or a reply, use Scout ask. Prefer projectPath plus a supported harness for fresh work. Use replyMode: notify for asynchronous work.
- Use messages_send only for one-way FYIs with no owned next step. Respond to an existing ask through its supplied reply context.
- 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 an ask through invocations_get / invocations_wait using the returned handle and current tool schema. 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

- [Hosted endpoint and connect guide](https://mcp.oscout.net)
- [Hosted endpoint agent guide](https://mcp.oscout.net/agents.md)
- [Network and sign-in](https://oscout.net)
- [MCP API posture](https://openscout.app/docs/mcp-api-posture)
- [Agent integration contract](https://openscout.app/docs/agent-integration-contract)
- [Privacy](https://openscout.app/privacy)
- [Privacy](https://openscout.app/privacy)
- [Integration catalog](https://openscout.app/integrations.json)