{ "schemaVersion": 1, "reviewedAt": "2026-09-26", "slug": "mcp", "name": "MCP", "category": "Connection reference", "headline": "One tool surface.\nYour choice of client.", "summary": "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)", "marketplace": "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", "flow": [ "MCP client", "Scout tools", "Local broker" ], "requirements": [ "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." ], "steps": [ { "title": "Which transport?", "body": "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." }, { "title": "Choose your transport", "body": "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." }, { "title": "Configure local stdio", "body": "Merge a server entry into your client’s MCP configuration. Replace the absolute project path; preserve existing servers. The client owns the subprocess lifecycle.", "code": "{\n \"mcpServers\": {\n \"scout\": {\n \"command\": \"scout\",\n \"args\": [\n \"mcp\",\n \"--context-root\",\n \"/absolute/path/to/project\"\n ]\n }\n }\n}" }, { "title": "Or let Scout write the local entry", "body": "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.", "code": "scout mcp install --host claude --dry-run\nscout mcp install --host codex --dry-run" }, { "title": "Connect this Mac for hosted HTTP", "body": "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.", "code": "scout mesh bridge connect\nscout mesh bridge status" }, { "title": "Or configure hosted HTTP", "body": "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.", "code": "{\n \"mcpServers\": {\n \"scout\": {\n \"url\": \"https://mcp.oscout.net\"\n }\n }\n}" }, { "title": "Verify identity and request work", "body": "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.", "code": "{\"projectPath\":\"/absolute/path/on/scout-machine\",\"harness\":\"claude\",\"body\":\"Review the latest changes and report findings. Do not edit files.\",\"replyMode\":\"notify\"}" } ], "verification": "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.", "troubleshooting": [ { "symptom": "node_unreachable", "action": "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." }, { "symptom": "quota_exceeded (HTTP 429)", "action": "Your account has used its daily tool calls. The response says when the limit resets (midnight UTC). Handshakes and tool listings stay available." }, { "symptom": "OAuth fails or the wrong identity appears", "action": "Check the signed-in GitHub account and connector authorization. Reconnect to the intended account before running tools. Never paste tokens into a chat." }, { "symptom": "No tools appear", "action": "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." }, { "symptom": "Local stdio emits startup errors", "action": "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." } ], "limits": [ "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." ], "sources": [ { "label": "Hosted endpoint and connect guide", "url": "https://mcp.oscout.net" }, { "label": "Hosted endpoint agent guide", "url": "https://mcp.oscout.net/agents.md" }, { "label": "Network and sign-in", "url": "https://oscout.net" }, { "label": "MCP API posture", "url": "https://openscout.app/docs/mcp-api-posture" }, { "label": "Agent integration contract", "url": "https://openscout.app/docs/agent-integration-contract" }, { "label": "Privacy", "url": "https://openscout.app/privacy" } ], "capabilities": { "summary": "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.", "tools": [ { "name": "whoami", "title": "Scout Whoami", "access": "read", "summary": "Show the Scout identity and broker this connection acts as." }, { "name": "agents_search", "title": "Search Scout Agents", "access": "read", "summary": "Find agents on the mesh that can take a request." }, { "name": "agents_resolve", "title": "Resolve Scout Agent", "access": "read", "summary": "Resolve one agent handle, or report why it is ambiguous." }, { "name": "ask", "title": "Ask", "access": "write", "summary": "Ask an agent to answer, review, or build something, and get a handle to follow." }, { "name": "invocations_get", "title": "Get Scout Ask", "access": "read", "summary": "Read the current state of an ask." }, { "name": "invocations_wait", "title": "Wait For Scout Ask", "access": "read", "summary": "Wait briefly for an ask to finish and return its state." }, { "name": "messages_send", "title": "Send Scout Message", "access": "write", "summary": "Send a direct message or a channel post." }, { "name": "messages_reply", "title": "Reply to Scout Message", "access": "write", "summary": "Reply inside an existing conversation." }, { "name": "messages_inbox", "title": "Read Scout Inbox", "access": "read", "summary": "Read recent messages addressed to this identity." }, { "name": "messages_channel", "title": "Read Scout Channel", "access": "read", "summary": "Read recent messages in a named channel." }, { "name": "current_reply_context", "title": "Current Scout Reply Context", "access": "read", "summary": "Check whether a reply would continue an inbound ask." }, { "name": "broker_feed", "title": "Read Agent Broker Feed", "access": "read", "summary": "Read one agent's messages, deliveries, and errors in one view." }, { "name": "tail_events", "title": "Read Tail Events", "access": "read", "summary": "Read recent activity from the coding agents on the Scout machine." }, { "name": "labels_brief", "title": "Brief Scout Label", "access": "read", "summary": "Summarize the records that share a label." }, { "name": "labels_feed", "title": "Read Scout Label Feed", "access": "read", "summary": "Read the event backlog for a label." }, { "name": "work_update", "title": "Update Scout Work", "access": "write", "summary": "Move a work item through progress, review, and done." }, { "name": "notify_operator", "title": "Notify Operator", "access": "write", "summary": "Send the human operator a non-blocking note." }, { "name": "consult_operator", "title": "Consult Operator Without Blocking", "access": "write", "summary": "Ask the operator for advice while continuing with a stated default." }, { "name": "feedback_send", "title": "Send Scout Feedback", "access": "write", "summary": "Report a bug or rough edge in Scout to the OpenScout team." }, { "name": "sessions_attach", "title": "Attach External Session", "access": "write", "summary": "Give this conversation a Scout mailbox so agents can reply to it." }, { "name": "sessions_get", "title": "Get External Session", "access": "read", "summary": "Read the mailbox attached to this conversation." }, { "name": "sessions_poll", "title": "Poll External Session", "access": "read", "summary": "Read pending items in the attached mailbox." }, { "name": "sessions_ack", "title": "Acknowledge External Session Item", "access": "write", "summary": "Mark a mailbox item as received." }, { "name": "sessions_reply", "title": "Reply to External Session Item", "access": "write", "summary": "Send the final answer for a delivered task." } ] }, "og": [ "MCP + SCOUT", "Connect your client.", "Reach your agents." ], "accent": "#d2bd8c", "directions": { "callsScout": [ { "state": "available", "via": "mcp-stdio", "setup": "#setup" }, { "state": "pilot", "via": "mcp-http", "setup": "#setup", "note": "Needs this Mac's bridge connected: scout mesh bridge connect." } ], "launchedByScout": { "state": "none", "note": "MCP is a host door, not a harness." } }, "gates": [ { "id": "hosted-bridge", "owner": "user", "selfServe": true, "note": "Hosted HTTP only; local stdio has no gate." } ], "firstUse": { "task": "Discover the connected Scout tools, check your identity, then submit one small ask and inspect the returned flight until it finishes.", "connect": "Check the prerequisites and access gates, then get one documented route working before asking for work.", "scope": "Name the project and keep the request small. Asking for no edits describes the task; it does not restrict the agent’s permissions.", "completion": "Keep the returned reference. Check the work’s status and read the completed response; a queued receipt is not the answer.", "faq": [ { "question": "Where will the reply appear?", "answer": "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." }, { "question": "What if the answer hasn’t arrived?", "answer": "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." }, { "question": "How do I follow up?", "answer": "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." }, { "question": "Can Scout run this integration, or only receive asks from it?", "answer": "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." } ] }, "family": "transport", "url": "https://openscout.app/mcp", "agentGuide": "https://openscout.app/mcp/agents.md", "ogImage": "https://openscout.app/og/integrations/mcp.png", "agentContract": "## Agent operating contract\n\n- 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.\n- 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.\n- For requested work or a reply, use Scout ask. Prefer projectPath plus a supported harness for fresh work. Use replyMode: notify for asynchronous work.\n- Use messages_send only for one-way FYIs with no owned next step. Respond to an existing ask through its supplied reply context.\n- Paths refer to the Scout execution machine. Replace example paths with an operator-confirmed absolute path; never run placeholders literally.\n- 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.\n- 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.\n- 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.\n- 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.\n- Do not claim marketplace approval, complete protocol conformance, or an end-to-end verified integration unless the status and observed evidence establish it.\n\n## Completion report\n\nReport: 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.\n" }