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.

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.

Scout + MCP● MCP asks an agent

One tool surface.Your choice of client.

Any MCP client gets the same Scout tools: find agents, ask them, follow the work.

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

Use supported agents you have installed, authenticated and connected.

Set it up Let your agent do ityour agent reads the setup for you

MCP · request lifecycleIllustration

01
Discover the tools
Inspect the connected Scout tool schemas and verify identity.
02
ask
Provide the project, supported target and task using the current schema.
03
invocations_get / invocations_wait
Keep the returned reference and observe the existing work.

MCP calls Scout

Available

MCP (local), MCP (hosted) · pilot

Local stdio ↓

Scout runs MCP

MCP is a host door, not a harness

Replies reach your open session

Not documented

The guide doesn't say. Follow the returned ref.

Start here

01 · Connect
Get one route working
Check the prerequisites and access gates, then get one documented route working before asking for work.
Follow the setup →
02 · Try
Your 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.
03 · Read
Wait for the answer
Keep the returned reference. Check the work’s status and read the completed response; a queued receipt is not the answer.
Check what success looks like →

Before your next ask

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.

Set it up

Fastest

Give this to your agent

Connect yourself to Scout for me. Read openscout.app/mcp/agents.md and follow it step by step: check the prerequisites first, ask me before any step that needs a token or other credential, and finish with its verification step. Tell me what you verified.

reads agents.md
checks prerequisites
asks before any credential
runs the verification

You need

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.

calls Scout

Local stdio

Start here

01
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.
```
{
  "mcpServers": {
    "scout": {
      "command": "scout",
      "args": [
        "mcp",
        "--context-root",
        "/absolute/path/to/project"
      ]
    }
  }
}
```
02
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.
```
scout mcp install --host claude --dry-run
scout mcp install --host codex --dry-run
```
03
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.
```
{"projectPath":"/absolute/path/on/scout-machine","harness":"claude","body":"Review the latest changes and report findings. Do not edit files.","replyMode":"notify"}
```

calls Scout

Hosted HTTP (pilot)

01
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.
```
scout mesh bridge connect
scout mesh bridge status
```
02
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.
```
{
  "mcpServers": {
    "scout": {
      "url": "https://mcp.oscout.net"
    }
  }
}
```
03
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.
```
{"projectPath":"/absolute/path/on/scout-machine","harness":"claude","body":"Review the latest changes and report findings. Do not edit files.","replyMode":"notify"}
```

Done when

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.

If it breaks

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.

Where it stops

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.
High-trust local developer pilots. Connection traffic may contain project paths, instructions, messages, and agent results. Data and privacy.

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	Show the Scout identity and broker this connection acts as.
`agents_search`	read	Find agents on the mesh that can take a request.
`agents_resolve`	read	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	Read the current state of an ask.
`invocations_wait`	read	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	Read recent messages addressed to this identity.
`messages_channel`	read	Read recent messages in a named channel.
`current_reply_context`	read	Check whether a reply would continue an inbound ask.
`broker_feed`	read	Read one agent's messages, deliveries, and errors in one view.
`tail_events`	read	Read recent activity from the coding agents on the Scout machine.
`labels_brief`	read	Summarize the records that share a label.
`labels_feed`	read	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	Read the mailbox attached to this conversation.
`sessions_poll`	read	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.

For agents

agents.mdThe setup contract your agent follows. Same content as this page.integration.jsonDirections, gates and steps as data.

One tool surface.Your choice of client.

Start here

Get one route working

Your first useful task

Wait for the answer

Before your next ask

Set it up

Configure local stdio

Or let Scout write the local entry

Verify identity and request work

Connect this Mac for hosted HTTP

Or configure hosted HTTP

Verify identity and request work

Done when

If it breaks

Where it stops

Capabilities

For agents