{ "schemaVersion": "1.0", "title": "Connect over MCP", "nodes": [ { "type": "nav", "id": "nav", "props": { "variant": "bar", "title": "Nano Workforce", "items": [ { "label": "Overview", "page": "overview" }, { "label": "Connect over MCP", "page": "mcp" }, { "label": "Lineage", "page": "lineage" }, { "label": "Convergence", "page": "home" }, { "label": "Epics", "page": "epic" }, { "label": "Feature", "page": "feature" }, { "label": "Delivery Graphs", "page": "delivery-graphs" }, { "label": "Tasks", "page": "tasks", "badge": { "source": "app", "table": "user_tasks", "filter": [], "tone": "danger", "refreshMs": 5000, "hideWhenZero": true } }, { "label": "Cockpit", "page": "cockpit" }, { "label": "Board", "page": "board" }, { "label": "Velocity", "page": "velocity" } ], "sticky": true } }, { "type": "text", "id": "title", "props": { "text": "Connect over MCP", "variant": "heading" } }, { "type": "text", "id": "intro", "props": { "text": "Point a coding agent (Copilot, Claude, Cursor \u2026) at this running instance so the workforce's operations become native tools \u2014 submit work, answer escalations, read status, and debug a wedged instance without curl. The Urban runtime serves a Streamable-HTTP MCP endpoint for this app at the /app/mcp path \u2014 behind a reverse-proxy prefix the reachable URL carries that prefix, as the recipes below render \u2014 and projects its openapi.yaml into tools, with zero MCP code in nwf. Register ONE server entry per instance; its tools are namespaced under the name you give it, so naming the instance targets the right one and makes the wrong-instance mistake very hard to hit (a server pointed at the wrong URL can still misfire). Use the copyable recipes below \u2014 each URL is already rendered for THIS instance's address (including any reverse-proxy prefix).", "variant": "sub" } }, { "type": "button", "id": "recipe-config", "props": { "label": "\ud83d\udccb Config recipe \u2014 local / LAN / remote (mcp-config.json)", "variant": "ghost", "modal": { "title": "One server entry per instance", "description": "Add to ~/.copilot/mcp-config.json (user-wide) or .mcp.json (repo-scoped). The workforce-local entry is pre-filled with THIS instance's URL; the merlin/remote entries show the LAN and ngrok shapes \u2014 give each node its own named entry. If THIS instance is guarded (NANO_PR_WEBHOOK_SECRET set), add the same \"headers\": { \"x-hook-secret\": \"$NANO_PR_WEBHOOK_SECRET\" } block to workforce-local too, or its calls 401. MCP servers register at host startup, so add the entry, THEN start a new session for its tools to load.", "copyLabel": "Copy config", "copyText": "{\n \"mcpServers\": {\n \"workforce-local\": {\n \"type\": \"http\",\n \"url\": \"{{appBase}}app/mcp\",\n \"tools\": [\"*\"]\n },\n \"workforce-merlin\": {\n \"type\": \"http\",\n \"url\": \"http://merlin.local:3000/app/mcp\",\n \"headers\": { \"x-hook-secret\": \"$NANO_PR_WEBHOOK_SECRET\" },\n \"tools\": [\"*\"]\n },\n \"workforce-remote\": {\n \"type\": \"http\",\n \"url\": \"https://.ngrok.app/app/mcp\",\n \"headers\": { \"x-hook-secret\": \"$NANO_PR_WEBHOOK_SECRET\" },\n \"tools\": [\"*\"]\n }\n }\n}" } } }, { "type": "button", "id": "recipe-cli", "props": { "label": "\ud83d\udccb CLI form (copilot mcp add)", "variant": "ghost", "modal": { "title": "Add from the terminal", "description": "For a guarded instance (NANO_PR_WEBHOOK_SECRET set), pass the shared-secret header with the --header form (the second command); an unguarded instance needs only the first.", "copyLabel": "Copy commands", "copyText": "# This instance if unguarded (no NANO_PR_WEBHOOK_SECRET set):\ncopilot mcp add --transport http workforce-local {{appBase}}app/mcp\n\n# This instance if guarded (NANO_PR_WEBHOOK_SECRET set) \u2014 present the shared secret header:\ncopilot mcp add --transport http workforce-local {{appBase}}app/mcp \\\n --header \"x-hook-secret: $NANO_PR_WEBHOOK_SECRET\"" } } }, { "type": "text", "id": "tractable-heading", "props": { "text": "Import a curated tool set (tractable surface)", "variant": "heading" } }, { "type": "text", "id": "tractable-body", "props": { "text": "The full projected surface is ~56 tools / ~79 KB of tools/list (app operations plus the framework urban_debug_* engine family) \u2014 large enough that a coding-agent harness may defer the whole set behind a tool-search gate, and \"tools\": [\"*\"] imports every one eagerly. Prefer a curated allowlist of the tools you actually drive and read with: set the server entry's \"tools\" to the curated subset instead of [\"*\"]. The curated list is maintained as the single source of truth in the repo (app/mcpToolSurface.ts, CURATED_MCP_TOOLS) and rendered as a copyable JSON block in the runbook \u2014 see docs/mcp-runbook.md \u00a7\"Import a curated subset\". [\"*\"] still works where the client does not defer; the full surface stays reachable either way.", "variant": "sub" } }, { "type": "text", "id": "session-recovery-heading", "props": { "text": "Recover a lost session (re-initialize on -32000)", "variant": "heading" } }, { "type": "text", "id": "session-recovery-body", "props": { "text": "The /app/mcp transport is stateful streamable-HTTP: every tool call carries an mcp-session-id, and a call with a missing / stale / idle-dropped / proxy-reset / evicted session id is refused with -32000 \"no valid session id, and not an initialize request.\" A client that does not re-handshake then sees the whole surface report \"tool does not exist\" until it re-initializes \u2014 a single hiccup (notably a heavy-tool timeout) can brick every tool. The self-heal is a fresh initialize handshake, which mints a new session and restores the entire catalogue in one round trip; a well-behaved MCP client does this automatically on a -32000. A stateless/resumable transport that removes the session dependency is tracked upstream (nano-ide#488).", "variant": "sub" } }, { "type": "text", "id": "secret-heading", "props": { "text": "Shared-secret setup (x-hook-secret)", "variant": "heading" } }, { "type": "text", "id": "secret-body", "props": { "text": "When this instance sets NANO_PR_WEBHOOK_SECRET, the guard is NOT mutation-only \u2014 it also covers reads, so read endpoints like GET /app/api/agent and GET /app/api/version return 401 without the x-hook-secret header, just as guarded mutations do. It is not blanket, though: a few doors stay intentionally unguarded even when the secret is set (e.g. the declarative Save-to-library page action, which structurally cannot attach the header). The mcp-config.json path takes the shared secret as a headers block, not a flag, so add a headers block alongside url on the server entry (copy it below); omitting it yields 401s. Put the secret in the server entry's headers, never in chat. When NANO_PR_WEBHOOK_SECRET is unset, the app guard is off entirely \u2014 reads and mutations both work with no credential from wherever this instance is reachable (with network.bind \"all\" that is the LAN, not just loopback), so unset it only where that exposure is acceptable. Note the runtime-served /app/mcp surface is an exception to that reachability: it is loopback-only by default and refuses non-loopback peers with a 403 even when network.bind is \"all\", until you also set URBAN_MCP_ALLOW_REMOTE=true \u2014 LAN/remote MCP clients need that knob in addition to a wide bind.", "variant": "sub" } }, { "type": "button", "id": "recipe-secret", "props": { "label": "\ud83d\udccb Shared-secret header block", "variant": "ghost", "modal": { "title": "Add the x-hook-secret header", "description": "Drop this headers entry alongside url on the guarded server's config-form entry.", "copyLabel": "Copy headers", "copyText": "\"headers\": { \"x-hook-secret\": \"$NANO_PR_WEBHOOK_SECRET\" }" } } }, { "type": "text", "id": "basic-auth-heading", "props": { "text": "Basic-Auth-fronted instances (reverse proxy)", "variant": "heading" } }, { "type": "text", "id": "basic-auth-body", "props": { "text": "These are two different layers. x-hook-secret is the app's own guard, checked by nwf. Basic Auth is enforced by whatever fronts the instance (ngrok edge, console proxy) and 401s before the request ever reaches nwf. A Basic-Auth-fronted instance therefore needs BOTH headers on the connection: Authorization: Basic \u2026 for the proxy AND x-hook-secret for the app. Generate the blob with printf '%s' 'user:pass' | base64 (echo appends a newline and yields the wrong value); Base64 is encoding, not encryption \u2014 only use Basic Auth over HTTPS.", "variant": "sub" } }, { "type": "button", "id": "recipe-basic-auth", "props": { "label": "\ud83d\udccb Basic-Auth + secret (both headers)", "variant": "ghost", "modal": { "title": "Both headers, two different layers", "description": "Proxy layer (Authorization) plus app layer (x-hook-secret) on the same server entry.", "copyLabel": "Copy headers", "copyText": "\"headers\": {\n \"Authorization\": \"Basic \",\n \"x-hook-secret\": \"$NANO_PR_WEBHOOK_SECRET\"\n}" } } }, { "type": "text", "id": "mutation-guard-heading", "props": { "text": "urban_debug_* mutation-guard caveat", "variant": "heading" } }, { "type": "text", "id": "mutation-guard-body", "props": { "text": "The framework's mutating engine-debug tools (set_variables / retry_job / resolve_incident / cancel_instance) require the app's shared-secret scheme (or the loopback-only allowMutations opt-in when allowRemote is off). Until issue #698 declares x-nano-secret-env, remote mutations are refused on any allowRemote-on instance even with reads open \u2014 that is the current posture, tracked in #698. The read tools (urban_debug_search_process_instances / _element_instance_wait_states / _incidents, and where projected _jobs / _variables) work under the same x-hook-secret as the rest of the surface. Operator-only doors stay operator-only: the delivery-graph stage / dispatch / dismiss lifecycle is x-mcp-excluded from the tool surface \u2014 the human clicking Dispatch in the cockpit IS the approval \u2014 so an agent cannot dispatch a delivery graph through MCP (it authors graphs through the pure compileDeliveryGraph / previewDeliveryGraph doors, which stay exposed).", "variant": "sub" } }, { "type": "text", "id": "fallback-heading", "props": { "text": "Fallback \u2014 no MCP client", "variant": "heading" } }, { "type": "text", "id": "fallback-body", "props": { "text": "Agents without an MCP client are unchanged \u2014 fetch and follow this instance's live operator guide over curl (the response is JSON with a skill markdown field). Add -H \"x-hook-secret: \" (and -u user:pass for a Basic-Auth-fronted instance) if this instance is guarded. That skill bootstraps you to the same live guide MCP exposes as the getAgentInstructions tool \u2014 or, over MCP, its addressable companion getAgentGuide(section?), which the runbook recommends over the ~43KB blob to avoid a tool-result overrun.", "variant": "sub" } }, { "type": "button", "id": "recipe-fallback", "props": { "label": "\ud83d\udccb Fallback curl (no MCP client)", "variant": "ghost", "modal": { "title": "The curl door is unchanged", "description": "Fetch this instance's live guide directly; add the header(s) if guarded.", "copyLabel": "Copy curl", "copyText": "curl -sS {{appBase}}app/api/agent/skill\n# guarded instance \u2014 add the shared secret (and Basic Auth if fronted):\ncurl -sS {{appBase}}app/api/agent/skill \\\n -H \"x-hook-secret: \"" } } }, { "type": "text", "id": "runbook-heading", "props": { "text": "Deeper reference", "variant": "heading" } }, { "type": "text", "id": "runbook-body", "props": { "text": "This served page is the short, always-reachable summary. The full runbook \u2014 discovery, debugging a wedged instance, guard posture, the projected-tool-schema notes and the regression harness \u2014 lives in the repo at docs/mcp-runbook.md (https://github.com/nanobpm/nano-workforce/blob/main/docs/mcp-runbook.md), with README.md \u00a7\"Configure an agent over MCP\" as its companion. Keep the two in sync: the runbook is the source of truth, this page is the served digest.", "variant": "sub" } } ] }