start-os/core/src/mcp/ARCHITECTURE.md

MCP Server Architecture

The Model Context Protocol server embedded in StartOS (core/src/mcp/).

Transport: Streamable HTTP (MCP 2025-03-26)

The server implements the Streamable HTTP transport from the MCP spec, not the older stdio or SSE-only transports. A single route (/mcp) handles all three HTTP methods:

Method	Purpose
POST	JSON-RPC 2.0 requests from client (initialize, tools/call, resources/read, etc.)
GET	Opens an SSE stream for server→client notifications (resource change events)
DELETE	Explicitly ends a session
OPTIONS	CORS preflight

A discovery endpoint at /.well-known/mcp returns {"mcp_endpoint":"/mcp"}.

Authentication

Every HTTP method (POST, GET, DELETE) validates the caller's session cookie via ValidSessionToken::from_header before processing. This reuses the same auth infrastructure as the main StartOS web UI — MCP clients must present a valid session cookie obtained through the normal login flow. Unauthenticated requests get a 401.

Session Lifecycle

1. Create: Client sends initialize via POST. Server generates a UUID session ID, creates an McpSession with a bounded mpsc channel (256 messages), and returns the ID in the Mcp-Session-Id response header.

2. Connect SSE: Client opens a GET with the session ID header. The server takes the receiver half of the notification channel (take_notification_rx) and streams it as SSE events. Only one GET connection per session is allowed (the rx is moved, not cloned).

3. Use: Client sends tool calls, resource reads, subscriptions via POST. All POST requests must include a valid session ID header — the server validates it against the session map before processing.

4. Teardown: Three paths:

   • Client sends DELETE -> session is removed, subscription tasks are aborted.
   • SSE stream disconnects -> CleanupStream's PinnedDrop impl removes the session.
   • Session is never connected -> background sweep task (every 30s) removes sessions older than 60s that never had a GET stream attached.

Module Structure

core/src/mcp/
├── mod.rs        — HTTP handlers, routing, MCP method dispatch, shell execution, CORS
├── protocol.rs   — JSON-RPC 2.0 types, MCP request/response structs, error codes
├── session.rs    — Session map, create/remove/sweep, resource subscriptions with debounce
└── tools.rs      — Tool registry (67 tools), HashMap<String, ToolEntry> mapping names → RPC methods + schemas

Tool Dispatch

tool_registry() returns a HashMap<String, ToolEntry>, each mapping:

• An MCP tool name (e.g. "package.start")
• A JSON Schema for input validation (sent to clients via tools/list)
• A backing RPC method name (usually identical to the tool name)
• Flags: sync_db (whether to flush DB sequence after success), needs_session (whether to inject __Auth_session)

When tools/call arrives:

1. Look up the tool by name via HashMap O(1) lookup.
2. Convert arguments from serde_json::Value to imbl_value::Value.
3. Special-case: If rpc_method is "__shell__" or "__package_shell__", dispatch to handle_shell_exec / handle_package_shell_exec directly (no RPC handler). Both set kill_on_drop(true) to ensure timed-out processes are terminated.
4. Otherwise, optionally inject __Auth_session into params, then call server.handle_command(rpc_method, params).
5. On success: if sync_db is true, flush the DB sequence. Return the result pretty-printed as a text content block.
6. On error: return the error as a text content block with is_error: true, using McpResponse::ok (MCP spec: tool errors are results, not JSON-RPC errors).

Shell Execution

Two shell tools bypass the RPC layer entirely:

• system.shell (__shell__): Runs /bin/bash -c <command> on the host with kill_on_drop(true). 30s default timeout, 300s max.
• package.shell (__package_shell__): Resolves the target package's subcontainer via Service::resolve_subcontainer, then runs /bin/sh -c <command> inside it via lxc-attach (also kill_on_drop(true)). Same timeout behavior.

Resource Subscriptions

Four resources are exposed:

• startos:///public — full public DB tree
• startos:///public/serverInfo — server metadata
• startos:///public/packageData — installed packages
• startos:///mcp/system-prompt — curated AI assistant context (text/plain)

Resource URIs are validated to only allow /public/** subtrees and the special /mcp/system-prompt path. Attempts to access non-public paths (e.g. startos:///private/...) are rejected.

resources/read parses the URI into a JsonPointer, calls ctx.db.dump(&pointer), and returns the JSON. The system prompt resource is handled as a special case, returning server info and version.

resources/subscribe creates a DbSubscriber that watches the patch-db for changes at the given pointer. Changes are debounced (500ms window): the subscriber collects multiple revisions and merges their DiffPatches before sending a single notifications/resources/updated notification over the SSE channel. The subscription task runs as a spawned tokio task; its JoinHandle is stored in the session so it can be aborted on unsubscribe or session teardown. Re-subscribing to the same URI aborts the prior subscription first.

CORS

• Preflight (OPTIONS): reflects the request's Origin, Access-Control-Request-Method, and Access-Control-Request-Headers back. Sets Allow-Credentials: true and caches for 24h.
• Normal responses (apply_cors): reflects the request's Origin header when present, falls back to * when absent. Exposes the Mcp-Session-Id header. This matches the behavior of the rpc-toolkit Cors middleware used by the main UI.
• CORS headers are applied to all response types: POST JSON-RPC, GET SSE, DELETE, and error responses.

Body Size Limits

POST request bodies are limited to 1 MiB:

1. Content-Length header is checked before reading the body (rejects oversized requests immediately).
2. After reading, the actual body size is re-checked as defense-in-depth for chunked transfers that lack Content-Length.