Skip to content

API Reference

James Daley edited this page May 15, 2026 · 9 revisions

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.


Route hierarchy

%%{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
Loading

Surface overview

%%{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
Loading

1. Identity and health

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

Response — GET /api/version

{
  "version": "0.11.0-alpha.1",
  "commit": "94cad65",
  "buildTime": "2026-05-15T00:00:00Z"
}

Response — GET /api/health

{ "status": "ok", "time": "2026-05-15T12:34:56Z", "version": "0.11.0-alpha.1" }

Response — GET /api/health/summary

{
  "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.


2. LAN discovery

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"
}

3. LAN client management

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

Body — POST /api/clients/{id}/privileges

{
  "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"] }

4. Pool management

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

Body — POST /api/pools (abbreviated)

{
  "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.


5. Onboarding profiles

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.


6. Governance bundles

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.


7. Configuration

Method Path Introduced Status
GET /api/config v0.1.0 stable
POST /api/config v0.1.0 stable

Full-document replace semantics: POST /api/config replaces the entire AppConfiguration document. Omitting any top-level key (activeProfile, mcpGateway, etc.) wipes it. Always GET the current document, mutate only what you need, and POST the 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).


8. Telemetry

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.

TelemetryEvent shape

{
  "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.


9. Activity ring and SSE

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)

SSE Last-Event-ID 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
Loading

The server emits id: on every activity frame. Dashboard snapshot events are not part of the resumable sequence and carry no id:.


10. Runtime inventory

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.


11. Diagnostics (PHASE-14 Slice A — v0.11.0)

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

Query params — GET /api/diagnostics/events

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

Response — GET /api/diagnostics/self-test

{
  "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.

Response — POST /api/diagnostics/clear (501)

{
  "succeeded": false,
  "errorMessage": "Diagnostics clear is not yet implemented. Functional clear-with-retention lands in PHASE-14 Slice E.",
  "httpStatus": 501
}

Aggregation logic

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.


12. MCP Gateway — port 8080

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" } }
    ]
  }
}

13. HTTP status codes

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

14. Operation result envelope

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.


15. Quick-reference PowerShell session

$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/events

Related pages

Architecture · Telemetry-and-Activity · Worker-Pools · Gateway · Configuration · Privileges · Daily-Operations · Troubleshooting

Clone this wiki locally