EVERY TOOL CALL GOVERNED.

Each MCP server is an independent OAuth2 resource server with its own audience, scopes, and signing material. The validate_oauth_configs function in the registry validator rejects any enabled server that requires OAuth but defines no scopes, catching misconfiguration at deploy time rather than at runtime. The enforce_rbac_from_registry function in the RBAC middleware loads the per-server OAuth configuration, validates JWT bearer tokens, checks the audience claim against the server's configured audience, and validates scopes against the caller's permission set before any request reaches the tool runtime.

Scope elevation is blocked by Permission::implies. The validate_scopes_for_permissions function compares each required scope against the caller's permissions using user_perm.implies(required), so a caller cannot satisfy a higher-privileged scope by holding a narrower one. Proxy-verified requests flow through try_proxy_verified_auth, which validates x-proxy-verified, x-user-id, and x-user-permissions headers before granting access.

Credential rotation happens per server. The validate_jwt_token function in auth.rs validates tokens against a configurable JWT secret, issuer, and audience list per server, so rotating the database server's client secret leaves the file server untouched. The AuthResult enum separates Anonymous and Authenticated paths cleanly. Unauthenticated requests to an OAuth-required server return a structured MCP error rather than being silently downgraded.

Every tool call flows through a governed pipeline. The McpToolExecutor::execute method wraps every handler invocation. It serialises input arguments, generates a unique McpExecutionId, delegates to the McpToolHandler::handle trait method, records execution status (success or failure), and persists the full execution record via ToolUsageRepository. There is no second path. Tool calls that bypass the executor do not exist in the codebase.

The McpToolHandler trait enforces type safety at compile time. Input types must implement DeserializeOwned + JsonSchema. Output types must implement Serialize + JsonSchema + McpOutputSchema. The McpOutputSchema trait generates validated JSON schemas with x-artifact-type metadata for 11 artifact types including TextArtifact, TableArtifact, ChartArtifact, and DashboardArtifact. If the crate compiles, the tool contract is valid.

The DatabaseSessionManager implements the rmcp SessionManager trait with database-backed persistence. Sessions survive server restarts via persist_create and persist_close. The resume method detects sessions that exist in the database but not in memory (server restart scenario) and signals clients to reconnect cleanly. Activity tracking via update_activity enables session timeout enforcement. Every MCP operation flows through the same permission, audit, and session infrastructure.

All MCP servers are discoverable from a single registry. The RegistryService::get_enabled_servers_as_config method loads the global configuration, builds the ExtensionRegistry, filters for enabled servers (skipping dev_only servers in cloud mode), resolves crate paths for internal servers, and returns a complete McpServerConfig for each, including name, port, OAuth requirements, schema definitions, tool configuration, and environment variables. One call returns the full fleet inventory.

The validate_registry function runs four validation passes before any server starts: validate_port_conflicts detects duplicate port assignments across enabled servers using a HashSet. validate_server_configs checks that internal servers have valid ports (above 1024) and existing crate paths. validate_oauth_configs rejects OAuth-enabled servers with empty scope definitions. validate_server_types ensures internal servers have binaries and external servers have remote endpoints. All four pass or no servers start.

The RegistryManager implements three registry traits: McpRegistry for server discovery (list_servers, find_server, server_exists), McpToolProvider for tool enumeration (list_tools, load_tools_for_servers), and McpRegistryProvider for external consumers (get_server, list_enabled_servers with ServiceOAuthConfig). The registry supports both McpServerType::Internal (compiled binaries) and McpServerType::External (remote endpoints). Each internal server binds its own port. The default range is (5000, 5999), set by default_mcp_port_range in settings.rs.

Agent-tool mappings are explicitly declared in plugin configuration. The validate_single_server function checks each server's structural validity: internal servers must have ports above 1024 and existing crate paths, display names and descriptions must be non-empty, external servers must have remote endpoints and no binary references. There are no implicit permissions. If a tool is not declared in the plugin manifest, it does not exist for that agent.

The validate_and_migrate_schemas function creates a SchemaValidator with configurable validation modes (strict, warn, skip) and runs validate_and_apply against every server's declared schemas. Tables are created if missing. Schema errors are collected and reported. If any server fails validation, the entire orchestration halts. The SchemaValidationReport tracks validated count, created count, and error messages for full observability.

Configuration drift is detectable and preventable. The validate_server_type_constraints function ensures internal servers have binaries and external servers have remote endpoints, preventing mismatched server type configurations. The McpDeploymentProviderImpl exposes the protocol version (2024-11-05) for version tracking. The ServiceStatus struct captures runtime state (health, PID, uptime, tools count, latency, auth requirement) for comparison against declared configuration.

The LifecycleManager coordinates startup, shutdown, health monitoring, and restart for every MCP server. The start_server function follows a strict sequence. It verifies binary existence via ProcessManager::verify_binary, prepares the port via NetworkManager::prepare_port, waits for port release using MAX_PORT_CLEANUP_ATTEMPTS = 5 with PORT_BACKOFF_BASE_MS = 200 (defined in port_manager.rs), spawns the server process via ProcessManager::spawn_server, then runs up to 15 health check attempts. The delay schedule is set in startup.rs: max_attempts = 15 and base_delay = 300ms, with calculate_delay returning Duration::ZERO on attempt 1 and base_delay * min(attempt, 5) thereafter, capping at 1500ms. Only after HealthStatus::Healthy is confirmed does the server register in the database with its PID and startup time.

Shutdown follows the inverse path. The stop_server function finds the running process (checking both database PID and port-based detection), sets status to "stopping", calls ProcessManager::terminate_gracefully (SIGTERM), waits 500ms, then ProcessManager::force_kill (SIGKILL) if the process survives. The finalize_shutdown function updates the database status to "stopped", clears the PID, and calls NetworkManager::cleanup_port_resources. The cleanup_stale_state function handles servers that are already stopped but have lingering database entries.

The reconcile function in the orchestrator runs on every startup. cleanup_stale_services and delete_crashed_services clear dead entries, delete_disabled_services removes servers no longer in configuration, validate_schemas ensures database tables exist, detect_and_handle_orphaned_processes kills processes with no matching registry entry, detect_and_handle_stale_binaries kills processes running outdated binaries, then kill_all_running_servers stops everything before start_pending_servers brings the fleet up fresh. The monitor_health_continuously function runs an interval-based health loop with HealthMonitorState tracking failure counts and downtime duration for automatic recovery detection.