Repository navigation
API Reference
Type: Reference · Audience: Operators, AI clients, dashboard integrators · Version:
v0.11.0-alpha.1· Updated: 2026-05-15
MCOS exposes two distinct HTTP surfaces from one process. The Admin API on port 7300 handles operator-facing management, dashboard polling, and AI-client management. The MCP Gateway on port 8080 is the MCP JSON-RPC endpoint LAN AI clients connect to. Both are served by MasterControlServiceHost.exe via the native HTTP.sys adapter. There is no separate process — one binary, one runtime, two ports.
LAN trust is by design: auth=none, trust=lan. App-layer auth is deferred to the retail build. Do not propose adding auth to this alpha.
%%{init: {'theme':'dark', 'themeVariables': {'primaryColor': '#031018', 'primaryTextColor': '#E6FCFF', 'primaryBorderColor': '#00f6ff', 'lineColor': '#5A00E8', 'secondaryColor': '#031827', 'tertiaryColor': '#0a1018'}}}%%
mindmap
root((MCOS HTTP))
:7300 Admin API
/api/version
/api/health
/api/health/summary
/api/discovery
/api/clients
/{id}
/{id}/privileges
/{id}/enable
/{id}/disable
/api/pools
POST upsert
/{id}/drain
/{id}/scale
DELETE /{id}
/api/onboarding/{type}
/api/governance/bundles
/{platform}
/api/config GET+POST
/api/telemetry
/events
/heartbeat
/api/activity
/health
/api/events SSE
/api/runtime
/mcp-servers
/subagents
/subagent-groups
/api/diagnostics
/events
/summary
/self-test
/export
/clear 501
:8080 MCP Gateway
POST /mcp
GET /health
%%{init: {'theme':'dark', 'themeVariables': {'primaryColor': '#031018', 'primaryTextColor': '#E6FCFF', 'primaryBorderColor': '#00f6ff', 'lineColor': '#5A00E8', 'secondaryColor': '#031827', 'tertiaryColor': '#0a1018'}}}%%
flowchart LR
classDef core fill:#031018,stroke:#00F6FF,color:#E6FCFF,stroke-width:2px;
classDef ext fill:#031827,stroke:#5AE8FF,color:#A8DCFF;
classDef pool fill:#031a14,stroke:#1cf2c1,color:#a8efe0;
classDef gov fill:#1a0a18,stroke:#ff00d9,color:#ffd1f3;
classDef store fill:#0a0a1a,stroke:#5a00e8,color:#d4c4ff;
Browser["Browser or curl"]:::ext
Shell["WinUI Shell"]:::ext
AI["LAN AI Client"]:::ext
Browser -->|"HTTP :7300"| Admin["Admin API :7300"]:::core
Shell -->|"HTTP :7300"| Admin
AI -->|"HTTP :7300"| Admin
AI -->|"MCP JSON-RPC :8080"| GW["MCP Gateway :8080"]:::pool
Admin --> HealthR["/api/version /api/health/*"]:::core
Admin --> CliR["/api/clients/*"]:::core
Admin --> PoolR["/api/pools/*"]:::core
Admin --> TelR["/api/telemetry/* /api/events SSE"]:::store
Admin --> DiagR["/api/diagnostics/*"]:::gov
Admin --> RunR["/api/runtime/*"]:::core
GW --> MCPPost["POST /mcp JSON-RPC"]:::pool
GW --> GWHealth["GET /health probe"]:::pool
| Method | Path | Introduced | Status |
|---|---|---|---|
GET |
/api/version |
v0.1.0 | stable |
GET |
/api/health |
v0.1.0 | stable |
GET |
/api/health/summary |
v0.6.0 | stable |
{
"version": "0.11.0-alpha.1",
"commit": "94cad65",
"buildTime": "2026-05-15T00:00:00Z"
}{ "status": "ok", "time": "2026-05-15T12:34:56Z", "version": "0.11.0-alpha.1" }{
"status": "ok",
"pools": { "total": 32, "darkOrQuarantined": 0 },
"gateway": { "state": "running", "health": "healthy" },
"uptime": "PT4H32M"
}gateway.health is "healthy" when the HTTP.sys adapter is bound and the pool catalog has been primed. "unknown" means the adapter probe failed — see Troubleshooting §5.
| Method | Path | Introduced | Status |
|---|---|---|---|
GET |
/api/discovery |
v0.3.0 | stable |
Returns the DiscoveryDocument that is also broadcast via DNS-SD and the UDP beacon. Clients that cannot use mDNS can poll this route directly after finding the host IP via out-of-band means.
{
"instanceId": "mcos-host-abc123",
"instanceName": "Master Control on PC-GAMING-R7-58",
"adminUrl": "http://192.168.1.10:7300",
"gatewayMcpUrl": "http://192.168.1.10:8080/mcp",
"onboardingUrl": "http://192.168.1.10:7300/api/onboarding",
"auth": "none",
"trust": "lan",
"protocolVersion": "1.0"
}| Method | Path | Introduced | Status | Notes |
|---|---|---|---|---|
GET |
/api/clients |
v0.5.0 | stable | Roster with presence + privilege data |
GET |
/api/clients/{id} |
v0.5.0 | stable | Single-client record |
POST |
/api/clients/{id}/privileges |
v0.5.0 | stable | Atomic full replace; droppedKeys on unknowns (v0.10.17) |
POST |
/api/clients/{id}/enable |
v0.5.0 | stable | Re-enable a disabled client |
POST |
/api/clients/{id}/disable |
v0.5.0 | stable | Soft-disable; sets disabledAtUtc
|
{
"canCreateMcpServers": true,
"canModifyMcpServers": false,
"canRemoveMcpServers": false,
"canCreateSubAgents": true,
"canModifySubAgents": false,
"canRemoveSubAgents": false,
"canManageClients": false,
"canManageModules": false,
"canChangeGovernancePolicy": false
}This call replaces the entire privilege struct. Omitted flags default to false. For partial updates: GET the current record, mutate the field, POST the full struct back. Unknown top-level keys are not rejected — they are returned in droppedKeys as an additive diagnostic field (v0.10.20).
{ "succeeded": true, "summary": "Privileges updated.", "droppedKeys": ["legacyFlag"] }| Method | Path | Introduced | Status | Notes |
|---|---|---|---|---|
GET |
/api/pools |
v0.6.0 | stable | All 32 pools |
POST |
/api/pools |
v0.6.0 | stable | Upsert pool definition; droppedKeys on unknowns (v0.10.17) |
POST |
/api/pools/{id}/drain |
v0.7.0 | stable | Gracefully drain all active leases |
POST |
/api/pools/{id}/scale |
v0.7.0 | stable | Scale to minInstances immediately |
DELETE |
/api/pools/{id} |
v0.7.0 | stable | Remove pool and all instances |
{
"poolId": "my-mcp-pool",
"kind": "mcp-server",
"logicalMcpUrl": "http://localhost:19000/mcp",
"template": {
"transport": "streamable_http",
"executablePath": "C:\\tools\\my-server.exe",
"arguments": [],
"environment": { "MY_VAR": "value" },
"workingDirectory": ""
},
"scalePolicy": {
"minInstances": 1,
"maxInstances": 4,
"maxActiveLeasesPerInstance": 8
}
}template.environment is honored as of v0.10.21. Prior versions silently passed nullptr for lpEnvironment, ignoring the block.
| Method | Path | Introduced | Status |
|---|---|---|---|
GET |
/api/onboarding/{type} |
v0.4.0 | stable |
{type} values: chatgpt, claude-code, codex, grok, generic.
Returns manual setup instructions, copyable config snippets, verification steps, and caveats for that client type. Claude Code clients can also receive this via the mcos-control plugin's mcos_get_onboarding_profile tool.
| Method | Path | Introduced | Status |
|---|---|---|---|
GET |
/api/governance/bundles |
v0.5.0 | stable |
GET |
/api/governance/bundles/{platform} |
v0.5.0 | stable |
{platform} values: windows, macos, ios. Each bundle carries Forsetti version, CLU schema version, sha256 checksum, and generated timestamp.
| Method | Path | Introduced | Status |
|---|---|---|---|
GET |
/api/config |
v0.1.0 | stable |
POST |
/api/config |
v0.1.0 | stable |
Full-document replace semantics:
POST /api/configreplaces the entireAppConfigurationdocument. Omitting any top-level key (activeProfile,mcpGateway, etc.) wipes it. AlwaysGETthe current document, mutate only what you need, andPOSTthe complete document back. See Configuration.
FileBackedConfigurationService re-seeds activeProfile.identity and missing baseline catalog endpoints if the on-disk config has been wiped (v0.10.x self-heal).
| Method | Path | Introduced | Status | Notes |
|---|---|---|---|---|
GET |
/api/telemetry/events |
v0.8.0 | stable | Alias-aware query params (v0.10.15) |
POST |
/api/telemetry/heartbeat |
v0.8.0 | stable |
droppedKeys on unknowns (v0.10.17) |
Alias-aware ?max= (v0.10.15): also accepts ?limit=, ?count=, ?n=, ?top=. Default 100 events, capped at ring size 512. All aliases are boundary-anchored — ?xmax= does not match.
{
"capturedAtUtc": "2026-05-15T08:42:13.812Z",
"component": "supervisor",
"severity": "warn",
"event": "pool_worker_restart",
"message": "Worker process exited unexpectedly, restarting (attempt 2/3)",
"data": { "poolId": "nexus", "pid": 14432, "exitCode": 1 }
}Severity values: info, warn, error, critical. Events at warn or higher persist to runtime\events.jsonl (v0.10.21+). info stays in-memory only.
Unavailable sentinel: -1.0 means "metric not reported by this client." Never 0.0. The dashboard's formatMetric() renders it as unavailable. This contract applies to all ClientHeartbeat and WorkerTelemetry numeric fields.
| Method | Path | Introduced | Status | Notes |
|---|---|---|---|---|
GET |
/api/activity |
v0.8.0 | stable | Ring snapshot |
GET |
/api/activity/health |
v0.8.0 | stable | Ring health metadata |
GET |
/api/events |
v0.8.0 | stable | SSE stream; Last-Event-ID + ?since= resume (v0.10.16) |
%%{init: {'theme':'dark', 'themeVariables': {'primaryColor': '#031018', 'primaryTextColor': '#E6FCFF', 'primaryBorderColor': '#00f6ff', 'lineColor': '#5A00E8', 'secondaryColor': '#031827', 'tertiaryColor': '#0a1018'}}}%%
sequenceDiagram
participant C as SSE Consumer
participant S as /api/events
C->>S: GET /api/events
S-->>C: id: 100 data: event A
S-->>C: id: 101 data: event B
Note over C: Connection drops
C->>S: GET /api/events Last-Event-ID: 101
S-->>C: id: 102 data: event C
Note over C: Or use query param alias
C->>S: GET /api/events?since=101
S-->>C: id: 102 data: event C
The server emits id: on every activity frame. Dashboard snapshot events are not part of the resumable sequence and carry no id:.
| Method | Path | Introduced | Status | Notes |
|---|---|---|---|---|
GET |
/api/runtime/mcp-servers |
v0.10.0 | stable | All registered MCP server endpoints |
GET |
/api/runtime/subagents |
v0.10.0 | stable | All registered sub-agent endpoints |
GET |
/api/runtime/subagent-groups |
v0.10.20 | stable | Sub-agent group metadata |
Current inventory: 32 pools (25 MCP + 7 sub-agents), 126 tools. Sub-agents: architect, forge, nexus, recon, scribe, sentinel, watchtower.
Five routes added in v0.11.0. Slices B–E (MCP plugin tools, WinUI panel, browser tab, SqliteDiagnosticsStore) are deferred to v0.11.x.
| Method | Path | Status | Notes |
|---|---|---|---|
GET |
/api/diagnostics/events |
alpha-stable |
?max=, ?severity=, ?source= filters |
GET |
/api/diagnostics/summary |
alpha-stable |
totalEvents + bySeverity + byComponent + latest5
|
GET |
/api/diagnostics/self-test |
alpha-stable | 40-row boot self-test; currently passed=40, failed=0
|
GET |
/api/diagnostics/export |
alpha-stable |
?format=markdown or ?format=json; markdown caps each severity section at 50 events |
POST |
/api/diagnostics/clear |
501 deferred | Honest stub; functional clear lands in Slice E |
| Param | Type | Description |
|---|---|---|
max |
int | Max events to return (default 100) |
severity |
string | Filter: info, warn, error, critical
|
source |
string | Filter by component name: runtime, supervisor, installer, shell
|
{
"passed": 40,
"failed": 0,
"rows": [
{ "category": "http_endpoint", "name": "admin_port_7300", "result": "pass", "message": "" },
{ "category": "gateway", "name": "gateway_adapter_running", "result": "pass", "message": "" }
]
}Self-test categories: http_endpoint, gateway, pool_handshake, sub_agent, telemetry, process.
{
"succeeded": false,
"errorMessage": "Diagnostics clear is not yet implemented. Functional clear-with-retention lands in PHASE-14 Slice E.",
"httpStatus": 501
}The diagnostics aggregator walks per-component events.jsonl files (plus their .1.jsonl rotated siblings) under %PUBLIC%\Documents\Master Control Orchestration Server\logs\. It reads from disk on each query. At current event volumes (~50–200 events across components) this is microsecond-class. At higher volumes, Slice E's SqliteDiagnosticsStore will add an in-memory ring.
Alpha caveat: The diagnostic store is in-memory in v0.11.0-alpha.1. A service restart clears accumulated state.
SqliteDiagnosticsStore+ persistence + retention land in Slice E.
| Method | Path | Status | Notes |
|---|---|---|---|
POST |
/mcp |
stable | MCP JSON-RPC — tools/list, tools/call, resources/list, etc. |
GET |
/health |
stable | Gateway adapter health probe |
The only shipping substrate is NativeHttpSysGatewayAdapter (HTTP.sys). MCPJungle is retired (ADR-003). The gateway serves 126 tools across 32 pools.
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"tools": [
{ "name": "architect__design_review", "description": "...", "inputSchema": { "type": "object" } }
]
}
}| Code | When |
|---|---|
200 OK |
Read succeeded or mutation applied |
400 Bad Request |
Invalid JSON or input validation failure |
403 Forbidden |
Client disabled, privilege missing, or CLU block |
404 Not Found |
Unknown route, id, or resource |
501 Not Implemented |
Honest stub — POST /api/diagnostics/clear only |
500 Internal Server Error |
Unhandled exception; body carries errorMessage
|
Every mutating route returns a uniform OperationResult:
{
"succeeded": true,
"summary": "Pool updated.",
"errorMessage": "",
"warnings": [],
"droppedKeys": []
}Routes with droppedKeys behavior (v0.10.17 / v0.10.20): POST /api/clients/{id}/privileges, POST /api/pools, POST /api/telemetry/heartbeat, POST /api/runtime/mcp-servers, POST /api/runtime/subagents, POST /api/runtime/subagent-groups.
$base = "http://127.0.0.1:7300"
# Identity
Invoke-RestMethod "$base/api/version"
Invoke-RestMethod "$base/api/health/summary"
# Diagnostics
Invoke-RestMethod "$base/api/diagnostics/self-test" | Select-Object passed, failed
Invoke-RestMethod "$base/api/diagnostics/events?severity=warn&max=20" | ConvertTo-Json -Depth 4
Invoke-RestMethod "$base/api/diagnostics/export?format=markdown" | Out-File diagnostics.md
# Pools
Invoke-RestMethod "$base/api/pools" | ConvertTo-Json -Depth 3
(Invoke-RestMethod "$base/api/pools").Count # expect 32
# Live SSE stream (requires curl; PowerShell cannot natively stream SSE)
# curl -N http://127.0.0.1:7300/api/eventsArchitecture · Telemetry-and-Activity · Worker-Pools · Gateway · Configuration · Privileges · Daily-Operations · Troubleshooting
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