Repository navigation
Sub Agents
A sub-agent is a kind of managed endpoint pool. Sub-agents share the same lifecycle, supervision, and lease routing infrastructure as MCP server pools — they differ only in the value of EndpointPoolKind. PHASE-06 unified the two so MCOS supervises both with one set of code paths.
For the full model (lifecycle, lease routing, autoscaling, drain semantics, HTTP routes), see Worker Pools.
flowchart LR
classDef gw fill:#031018,stroke:#00F6FF,color:#E6FCFF;
classDef pool fill:#031a14,stroke:#1cf2c1,color:#a8efe0;
classDef inst fill:#0a1018,stroke:#5A00E8,color:#A8DCFF;
Gateway[IMcpGateway adapter]:::gw
subgraph PoolA[ManagedEndpointPool<br/>kind = mcp-server]
IA[Instance]:::inst
IB[Instance]:::inst
end
subgraph PoolB[ManagedEndpointPool<br/>kind = sub-agent]
SA[Sub-agent instance]:::inst
SB[Sub-agent instance]:::inst
end
Gateway -->|"registered as one logical server each"| PoolA
Gateway -->|"registered as one logical server each"| PoolB
Both kinds register one logical server per pool with the gateway adapter. Autoscaled clones are not exposed individually (FORBIDDEN-CONTRACT §2.2). The lease router treats both kinds identically.
enum class EndpointPoolKind {
McpServer,
SubAgent
};Slugs: mcp-server, sub-agent. testEndpointPoolKindEnumRoundTrip pins the round-trip.
A sub-agent is a service that:
- Speaks MCP but is purpose-built around a domain (code review, test generation, documentation, etc.) rather than a protocol concern.
- Is owned by MCOS as a backend rather than imported as a third-party MCP server.
- May spawn under the same lifecycle conventions as MCP servers (Job Object containment, health probe, lease router) but represents a unit of cognitive specialization.
A pool with kind=mcp-server is a generic backend. A pool with kind=sub-agent carries the same shape but documents intent — the dashboard can color-code them differently if it chooses.
Before PHASE-06, MCOS shipped seven hardcoded sub-agents on fixed ports (7201–7207), each described as a separate Node service. That model was retired during the realignment:
- Hardcoded ports are gone — pools advertise their own logical URL via the gateway.
- Per-sub-agent registration through
/api/runtime/subagentsis preserved on the operator surface (ADR-001 catalog) but is no longer the runtime path. - Sub-agent lifecycle is supervised under Windows Job Objects, not as separate Node service hosts.
- The lease router selects backend instances; the gateway no longer addresses sub-agents directly.
The operator catalog under /api/runtime/subagents survives for backward-compatible read access from older operator tooling. Treat it as the legacy view; new pools register via POST /api/pools.
- Lifecycle, leases, autoscaling, drain → Worker Pools
- Single-logical-server registration with the gateway → Gateway §5
-
Operator catalog (legacy, ADR-001) → API Reference for
/api/runtime/subagents -
Schema →
docs/implementation/schemas/managed-endpoint-pool.schema.json
Source for this wiki is maintained under docs/wiki/ in the Master-Control-Orchestration-Server repository.
Setup
Connect Clients
Operate
- Daily Operations
- Dashboard
- Telemetry and Activity
- Gateway
- Worker Pools
- Sub-Agents
- Governance
- CLU Governance
- Privileges
Maintain
Troubleshoot
Reference