Add an operator MCP for project CRUD and mesh status

[NitayRabi]

Problem

There is no machine-friendly operator surface for external tools or automations to manage projects and inspect mesh state. The web UI and HTTP API cover some of this for humans, but they are not shaped as an MCP interface for agent/tool use.

Goal

Expose an MCP server for control-plane operations so tools and agents can:

• manage projects
• inspect node status
• inspect agent status
• inspect session/topology state

Initial scope

Project management:

• create project
• list projects
• get project
• update project
• delete/archive project
• optionally associate allowed nodes and/or agents

Status and topology:

• list nodes with health/status
• get node details
• list agents with health/status
• get agent details
• inspect trigger rules
• inspect active/recent sessions

Design constraints

• MCP should expose stable resource/tool shapes, not UI-shaped payloads.
• Authorization must be explicit; this is an operator surface with write access.
• Browser concerns should stay out of the MCP design.
• File path validation and node-local execution constraints must remain enforced server-side or node-side as appropriate.

Likely architecture

• Add a dedicated MCP server process or mount an MCP surface from the existing server.
• Back it with the same repository/control-plane state used by the web API.
• Reuse existing auth/session concepts only if they fit non-browser clients cleanly; otherwise introduce a token-based auth path.
• Keep project CRUD and status reads versioned and documented.

Open questions

• Should MCP be read-only first, then write operations later?
• Should project CRUD live entirely in the control plane, or partly delegate to nodes?
• How should long-running or stateful operations be represented?
• Do we want MCP resources, tools, or both for topology and session inspection?

Acceptance criteria

• A client can list nodes and agents with current status through MCP.
• A client can CRUD projects through MCP.
• The interface is documented well enough to build automation against it.
• Auth for MCP is explicit and separate from browser-only assumptions.

[NitayRabi]

Finalized Architectural Design: MCP-to-ACP Bridge

Following consultation, we have finalized the approach for to provide a unified discovery and execution layer.

The Architecture

1. Discovery & Orchestration (MCP North): acts as a local MCP Server for the orchestrator (Claude Code, OpenClaw, etc.). It exposes tools for discovering and triggering agents.
2. Execution (ACP South): acts as an ACP Client to talk to remote agents. It manages the JSON-RPC state machine, handshake, and session persistence.
3. Routing: Discovery info is used to populate metadata, allowing a single connection point to route to any discovered agent dynamically.

Key Tools

• : Returns a manifest of discovered remote agents and their capabilities.
• : Starts a remote ACP session via the bridge, returning the initial response and a local .
• : Handles multi-turn delegation by mapping the local ID to the persistent remote ACP connection.

Benefits

• Platform Agnostic: Works with any orchestrator that supports MCP (Claude Code, Hermes, OpenClaw).
• Session Persistence: Handles the messy session state in the bridge, keeping the orchestrator's context clean.
• Bypasses Sampling/HITL Issues: Avoids the human-in-the-loop requirements of the new MCP Sampling spec by managing the delegation as a discrete tool-driven task.

[Snailflyer]

For the MCP operator surface, I would keep project CRUD separate from session/topology truth, but link them with explicit receipts.

A useful shape for mutating tools:

• project id and operation id
• requested node/agent/session target
• auth principal and tool call id
• resolved node/agent identity
• live session id, if the operation touches an active session
• result: project-updated, session-target-resolved, applied-to-live-session, queued, stale-target, or denied

That lets an external orchestrator know whether it only changed control-plane state or actually affected the intended live agent/session. For long-running or stateful operations, I would return an operation id immediately, then expose an MCP resource for the receipt stream.

Related reference from my side: Faryo is a narrower project/mobile workbench for same live tmux-backed coding sessions. Its core proof is the same boundary: project or mobile control state is not enough unless the original live session consumes the action:
https://github.com/Snailflyer/faryo/releases/tag/v1.0.8

[m13v]

the seam isn't project CRUD, it's the 'inspect active/recent sessions' plus 'long-running operations' pair. MCP tools are request/response with no handle that outlives the call, and a resource read is a snapshot the instant you fetch it. a mesh op longer than one call forces the caller to invent its own polling and correlation, and session/topology state goes stale between the read and the next action. expose only tools and that statefulness leaks back onto every agent on the operator surface. cleaner split: an op-handle tool that returns an id, plus a status resource keyed by that id, so progress and final state live behind the surface, not in each client.