Runtime proof passed · identity boundary pending · 15 September 2026

Project-scoped MCP for Agent Mate

Status: design and implementation plan; not deployed. Date: 2026-09-15 Authorization: user approved proceeding and requested this artifact before implementation.

Outcome

A user selects an existing project, enables an approved MCP connection, and Agent Mate can use its permitted tools through the existing AIOS runtime. Access belongs to that project and account. The chat explains connection readiness and tool activity. Closing the dashboard does not stop autonomous work.

The four copied services have passed representative shadow checks. This demonstrates installation-level readiness, not project-scoped access or comprehensive tool correctness.

Hard constraints

• Do not modify aios-harness or create a replacement model/tool execution loop.
• Adapt Agent Mate to the existing runtime and its tool registration/call path.
• Dashboard HTTP and WebSocket management use the same authorization decisions. Neither transport confers authority itself.
• Preserve legacy administrator MCP behavior and unrelated Connections behavior.
• Develop and verify in shadow9455. No production deployment, commit or push is part of this authorization.
• Do not expose the dashboard home, provider secrets or unrelated project data to workers or MCP subprocesses.

Evidence from the existing code

Paths below refer to /tmp/agent-mate-discovery.

These are source-review findings, not proof that the proposed bridge is implemented or compatible.

User workflow

1. In a project's Connections panel, show approved available MCP connections by label and discovered tool descriptions. Keep installation commands, environment values and credentials out of the chooser.
2. The project owner chooses a connection and permitted tools. Explain what each tool can do; do not classify arbitrary tools as read-only based on their name.
3. Persist the grant using the authenticated account and a server-resolved immutable project identity. Reject stale selectors.
4. Show separate states: configured, checking, ready, unavailable, permission revoked. A successful installation-level Test alone does not make a project ready.
5. Agent Mate can offer the same selection in interactive chat. Chat and the manual panel submit the same backend operation.
6. During a task, emit correlated started/completed/failed/cancelled tool activity. Show safe descriptions, timing and authorized output links, not raw credentials or unrestricted argument dumps.
7. Revocation immediately blocks subsequent admission. Explain any operation already admitted whose external side effects cannot be undone.

Permission and configuration model

An administrator-approved server registration supplies a stable server identity and configuration revision. Names are display labels, not authority. Binding a connection to a server does not expose its command, URL headers or environment to the browser.

Reuse Connections ownership and resource bindings. Add an explicit MCP binding containing the server identity/revision and allowed tool names. Replacing a server command/endpoint must invalidate readiness and require explicit acceptance of the new revision; reusing a display name must not inherit trust.

Connection authentication must explicitly distinguish no credential from an assigned credential. Existing serialized credentials and API-provider requirements remain compatible. Only a registered keyless MCP binding permits no credential; an omitted credential must never silently bypass credential checks on existing providers.

Effective permission is the intersection of current account authority, active project binding, enabled connection, McpTools grant, approved server revision and allowed tool set. Agent-wide grants do not implicitly authorize every project. Start with exact tool-name permissions; document that argument-level resource authorization remains the adapter/server's responsibility.

Missing identities, unknown tools, removed accounts, replaced projects, unreadable policy and disconnected connections fail closed.

Execution architecture

Proposed path:

Project chat / Connections panel
  -> existing HTTP or WebSocket management adapter
  -> shared Connections authorization and persistence

Independent Agent Mate host
  -> authenticated task/project binding
  -> existing AIOS runtime and MCP client
  -> project-scoped MCP bridge
  -> approved external MCP service

The bridge is a protocol/permission adapter, not an agent engine. Prefer official rmcp for its MCP protocol implementation. It must be owned by an independent host/service lifecycle, not a dashboard socket or HTTP handler. Integrate service commands into the existing AIOS executable where appropriate; do not introduce another inference engine.

The runtime may see only bridge definitions for its bound project. Simply filtering tools/list is insufficient: tools/call must reauthorize each request, because tool schemas can remain cached in the runtime.

Before choosing the final launch mechanism, verify how runtime configuration, vault access, sessions and project paths resolve from AIOS_HOME. Do not solve isolation by copying the dashboard home, duplicating provider keys, changing global runtime configuration during concurrent work, or sharing one unrestricted worker among projects.

Authenticate the host-to-bridge association using an OS-authenticated private channel plus a server-issued task binding. A shared Linux UID alone does not identify a project. Request-supplied account/project IDs are not evidence of authority. Any capability must be scoped, short-lived, non-loggable and unavailable to other project workers. The exact delivery mechanism is a required implementation gate.

Upstream MCP processes must not inherit the dashboard environment/home. Use reviewed executable/endpoint definitions, minimal environment, output/time/concurrency bounds and scoped workspace/output storage. Browser tools are network-capable; command approval does not imply access to every host or project. Establish and test the allowed filesystem/network boundary before enabling real project access.

Revocation, recovery and events

Reauthorize discovery and every call against current persisted policy. Define call admission as the authorization linearization point. A revocation prevents later admission; signal cancellation for already running calls where supported, but never claim it reverses external effects.

Do not replay a tool invocation after an uncertain disconnect. Persist request identity and terminal/unknown state outside the dashboard. Reconnecting the chat restores activity history; it does not resubmit operations. Revoked tools may remain visible in an existing runtime's cached schema, but invocation must fail safely; newly granted tools become available through a verified supported refresh or a new task/runtime, not a harness change.

Activity records bind account, immutable project, task, runtime session, connection and request ID. Enforce the same ownership on activity replay and artifact access. Raw MCP output is untrusted content, never an authorization instruction. Output HTML needs isolated rendering; screenshot paths need authorized artifact publication rather than arbitrary file access.

Implementation sequence and completion gates

Tasks are sequential where contracts depend on earlier evidence. A source test or stub UI alone does not complete operational integration. Any incompatibility changes Agent Mate or this bridge design, never the harness.

Acceptance scenarios

• Account A grants project A extract_structure; the actual AIOS runtime invokes it on a local test page and returns its headings.
• Project B has no grant: neither discovery nor a manually supplied call can use that connection. Assert no upstream call occurred.
• Client submits another account/project/task identifier: rejected before upstream access.
• Allow one tool on a multi-tool service: an unlisted tool remains denied even when explicitly called.
• Revoke during a live session: next call denied without process restart; already admitted operation reported accurately.
• Remove/recreate a project or replace the server registration: old grants do not silently attach to the replacement.
• Keyless MCP works without a fabricated secret. Existing credential-backed Connections still reject missing/revoked keys.
• Close/reopen dashboard during work: independent task continues; progress resumes without executing the tool twice.
• Upstream timeout/crash and bridge restart: bounded failure or unknown outcome; no automatic side-effect replay.
• Two projects execute concurrently: no credential, file, output or event cross-access.
• HTTP and WebSocket requests produce equivalent ownership decisions, including expired/deleted accounts.
• Browser screenshot results are accessible only to authorized project users; raw server paths cannot be fetched arbitrarily.

Use synthetic pages, dummy credentials and disposable fixture projects first. Publish why each check matters, input, expected output, actual output and scope. Distinguish library fixtures, actual runtime integration and real dashboard browser checks. Never describe a planned check as passed.

Rollout and remaining boundaries

Keep project MCP unavailable until the execution and permission gates pass. Add readiness per connection rather than changing a global provider_execution flag to imply all Connections providers work. Preserve admin MCP tooling. Back up affected shadow configuration/data before activation; keep new grants explicit with no automatic grants to existing projects.

Remote OAuth/BYOK lifecycle, arbitrary untrusted server installation, channel onboarding and media generation remain later integration work. The design must support them without claiming they already work. The current page-structure parser is regex-based and style-inliner output is not guaranteed offline self-contained; their prior tests are representative, not exhaustive.

MCP-P01 progress — actual runtime proof

On 15 September 2026, an executable rmcp3.4 fixture ran through the existing shadow AIOS binary, using session.create and prompt.submit. A deterministic loopback model responder requested the MCP tool; no real provider or project was contacted.

This proves runtime/protocol compatibility and per-call denial behavior in a controlled fixture. It does not prove hostile-worker isolation, multi-account ownership, concurrent projects, or real Connections grant enforcement. Launch arguments and the fixture policy are supervisor-controlled test inputs, not a production identity mechanism. MCP-P01 remains in progress.

The next implementation requirement is a trusted account/project/task binding and policy boundary outside the worker's writable filesystem. The current host is single-owner and authenticates Unix peers by UID; that alone cannot distinguish multiple projects. Do not enable live project MCP access until this boundary is implemented and verified. Harness source and live services were not changed by the proof.

Durable task identity — implementation progress

The Connections backend now stores an immutable account, host, task and verified project association. It survives registry reopening and checks current project ownership. Revocation prevents an old task from being reactivated. MCP permission lookup uses that stored project identity and current connection grants.

Seven focused tests passed: persistence, wrong account/host/task, permanent revocation, replaced projects and removed policy accounts, unverified selectors, project reassignment, and current MCP grants/credential authority. The full Connections regression suite passed 32 tests. These tests use temporary SQLite databases and synthetic project directories.

Not deployed. Authenticated transport wiring and OS worker isolation remain pending. The API requires trusted service context; an untrusted host or account string is not authentication. No live project MCP access was enabled.

Authenticated submission wiring and worker storage checks

Implemented in the development dashboard: before a scoped Agent Mate send reaches the host, the adapter resolves the logged-in account, checks its server-configured host and project mapping, and persists the task binding in the authority-owned Connections registry. It uses the same deterministic project selection as Agent Mate. Extra identity fields in the command are rejected. Session identity and host assignment are rechecked before dispatch.

The opt-in task configuration is private, owned by the dashboard authority, and requires a different worker Linux UID. Absence of configuration preserves ordinary chat and creates no project MCP binding. This is not implicit permission to use MCP. The policy mapping is operator-controlled; it is not a browser-editable account or host selector.

Verification completed

• A real compiled dashboard accepted a disposable authenticated WebSocket send and created Alice's host/project binding before the synthetic Unix host received it.
• Forged owner fields, another account's project and stale revisions did not reach host execution.
• Same-UID worker configuration and non-private policy files were rejected.
• Removing the fixture session closed its existing socket.
• An installation without scoped configuration retained ordinary chat with zero MCP task bindings.
• In the running shadow worker's mount namespace as UID994, eight read/write attempts against an authority-only sentinel failed, including direct paths and paths through the dashboard process's root. The authority UID995 could read it. Sentinel removed afterwards.
• Existing MCP WebSocket management fixture passed. Four Agent Mate library regressions passed. Earlier Connections suite passed32 tests.

The dashboard test uses a synthetic Unix host to observe dispatch order; the separate runtime proof uses the actual AIOS execution loop. These do not yet establish a complete real-provider, multi-project bridge flow. The worker storage check enters the actual mount/UID boundary but does not inherit the service cgroup/seccomp filters.

Deployment state

Tested build is staged, not activated. The shadow deployment guard found two dashboard-owned AIOS processes and prevented their interruption. No live project grants, task configuration, runtime restart, production changes or harness edits were made. Deployment can use the existing guarded activation script once the dashboard has no active child processes. No new approval is requested.

Keyless MCP approvals and exact tool admission — 16 September 2026

Connections now supports MCP services without inventing an API key. A keyless definition names an operator-approved service, its revision and an explicit tool list. API connections still require credentials. Existing credential-backed definitions remain readable. The task resolver checks the stored project binding, current grant, selected tool, server revision and transport on each admission request. This is an authorization library, not yet the independent executable MCP bridge.

The existing aios connections operator command now supports allow-mcp --account ACCOUNT --server SERVER --revision REVISION --tool TOOL (repeat --tool for each permitted tool), and remove-mcp --account ACCOUNT --server SERVER. Both require the existing explicit --home. Approval replacement replaces the tool list rather than adding to it. Approval does not create a connection, project grant or running service. A revision is an operator-supplied identifier; the future adapter must derive and verify the actual upstream revision, rather than trust a worker-supplied value.

Verified with disposable data: all 36 Connections library tests passed, including four new keyless/exact-tool tests; 20 Connections UI tests passed. A compiled CLI fixture verified private policy storage, no vault creation, account isolation, invalid update preservation, approval replacement and safe repeated removal. Dashboard and CLI builds passed. No live service approvals or grants were created.

The UI can display keyless definitions and recognizes withdrawn service approvals. The connection creation form still needs a service/tool picker. The full web check remains blocked by the existing Banner component file-length violation; focused Connections lint, React purity and type checks passed. Independent bridge execution, trusted upstream resolution and end-to-end project MCP acceptance remain open.

Approved service picker and bridge admission — 16 September 2026

The Connections page now has an approved MCP service picker. Users name a connection, select a current service revision and explicitly choose tools. Saving does not create project access; the existing sharing controls grant that separately. Changed service approvals require fresh selections. Pending saves reject duplicate clicks, and rejected/failed saves preserve the form. Older backends show the no-approved-services state.

Real Chromium verification against a disposable compiled dashboard passed: one selected tool saved over the authenticated WebSocket without a key or implicit grant; an explicit project grant persisted; operator removal of service approval disabled new grants while existing access remained revocable. The page fit a 390-pixel viewport. All 25 Connections UI tests passed, along with focused lint, purity, TypeScript and the shadow build. The unrelated Banner file-length check still blocks the aggregate web check.

The dashboard-independent Connections library now includes authority-side keyless admission. A trusted supervisor supplies the immutable account/host/task/connection context. Each admission rereads the live account, policy, task binding, grants and a private operator-owned upstream descriptor. Changing the descriptor invalidates the captured SHA-256 revision. Files must be private, single-link regular files owned by the authority; symlinks are rejected. Secret-backed services are rejected by this keyless path.

The fingerprint covers the declared command/arguments or URL and artifact revision. It does not establish executable or script integrity; the isolated launcher must validate the actual deployed artifact. This module does not yet expose an authenticated worker channel or execute tools. Its trusted constructor must never be exposed as a browser/worker identity selector. The independent bridge still needs its authenticated task channel, rmcp transport, isolated upstream lifecycle and final runtime wiring. No MCP subprocess may be launched as the credential-owning authority.

Verification: 41 Connections tests passed, including five new admission tests for bound task/exact tool checks, revoked tasks, deleted accounts, removed policy, modified upstream configuration and private-file enforcement. CLI and dashboard rebuilt successfully. Frontend assets are updated in shadow; new backend binaries remain staged. No live approvals, grants, production changes or harness modifications were made.

Independent task admission channel — 16 September 2026

Implemented the aios mcp-authority command inside the existing AIOS executable. It has no dashboard lifetime dependency and does not initialize the default vault. The authority issues a private five-minute bearer ticket only for an already bound task with a currently granted tool. The ticket fixes account, host, task, connection, service and worker Linux UID in the authority registry. Only its SHA-256 digest is stored. Reissuing the same task/connection invalidates its previous ticket. Explicit revocation, expiry and current grant/account changes are checked on subsequent requests.

The private Unix endpoint verifies the OS peer UID and ticket on every request. Requests may list allowed tool names or check one tool; they cannot supply account/project/host/task overrides. It accepts at most eight concurrent requests, caps each input at4096 bytes, and bounds socket reads/writes to three seconds. Authority and worker UIDs must differ. Responses expose neither secrets nor launch commands and explicitly report tool_execution=false. Tickets are written only to newly created0600 files in a private operator directory, never printed by the CLI.

This endpoint is an admission service, not yet the MCP protocol or upstream executor. A separate-UID test client received a dummy ticket through process stdin. Production ticket delivery must still keep tickets inaccessible to other project workers. OS UID checks alone do not isolate projects sharing that UID. Supervisor issuance/renewal, completion-time revocation, rmcp transport and isolated upstream execution remain to be wired before live access can be enabled. Admission retries are not tool execution or exactly-once guarantees.

Verification completed:45 Connections tests passed. The compiled service accepted only the selected navigate tool from a different Linux UID. It rejected unknown tickets, forged identity fields, an oversized request, the wrong peer UID, old/revoked/expired tickets and removed grants. Reissuing to an existing output file failed without invalidating the existing ticket. The service ran without a dashboard process. CLI and dashboard builds passed. Existing dashboard MCP WebSocket add/list/test/remove, member/origin denial and administrator-revocation cancellation also passed against disposable fixtures. No upstream tool was executed.

The first channel fixture incorrectly used the repository's project ID instead of the operator-created grant principal; admission rejected it. The fixture now uses the principal returned by bind-project, and the final run passed. No authorization checks were weakened.

Deployment remains staged. No new live tickets, grants, services, dashboard restarts, production changes or harness edits were made.

Isolated local MCP execution — 16 September 2026

The existing AIOS executable now contains a Linux-only mcp-executor service and an internal bounded operation subprocess. An optionally configured authority forwards approved stdio calls to this separate executor over a Unix socket. The authority verifies the executor UID; the executor accepts only its configured authority UID. The executor route belongs to one exact account, host and task. A valid ticket for another task cannot use that workspace. Without an executor configuration, the existing admission-only mode remains unchanged. No dashboard-owned process is used for this lifetime.

The upstream is selected from the authority's approved descriptor, never from the worker's tool arguments. Tickets are not forwarded to the executor or upstream. The operation uses the existing AIOS MCP client; it is not a new agent/model loop. Compatibility with an actual rmcp3.4 server was verified. The client-facing rmcp bridge still needs implementation. Remote HTTP upstream execution is intentionally unavailable until its network and credential policy is implemented.

The executor requires a non-root identity and no_new_privs. The trusted supervisor must supply filesystem, process and network isolation; the command does not create that boundary by itself. The disposable verification launcher uses Linux mount/network/PID namespaces, a restricted root, read-only system/tool mounts, a dedicated writable work directory, and a non-root identity with dropped capabilities. It preserves host UID identity for Unix peer authentication. Private user namespace UID translation initially broke that peer check; the corrected launcher does not weaken authentication.

Calls have bounded input/output, one executor operation at a time, a configurable1–120-second deadline, process-group cleanup and child reaping. Operation memory is limited to1GiB, file size to64MiB, and serialized response size to1MiB. A timed-out fixture exposed zombie children; subreaper/group cleanup fixed that before the final run. These controls do not establish aggregate disk/process quotas or containment of a hostile server deliberately escaping its process group. A production per-task service/cgroup profile and pinned executable integrity remain activation prerequisites.

Before forwarding, the authority persists a call ID within the account/host/task/connection scope. Reusing it is rejected even after ticket replacement or registry reopening. Completed calls record completed; transport failures, timeouts and oversized output record unknown. A crash may leave submitted requiring reconciliation. No argument values or raw tool output enter this receipt table. This prevents silent replay; it is not a claim of exactly-once external effects.

Final verification

• An approved synthetic tool returned ISOLATED_MCP_OK from UID65534. Its authority-file read failed, host-loopback connection failed, system-file write failed, and a fixture secret environment variable was absent.
• Another valid task ticket, an unselected tool and duplicate call IDs caused zero additional upstream invocations. Ticket replacement did not allow replay.
• A two-second fixture deadline killed and reaped the delayed operation's process group. Oversized output was rejected. Retrying the uncertain call ID did not execute it again.
• Removing the project grant prevented upstream contact. Receipts recorded the successful call as completed and the two uncertain operations as unknown.
• A real rmcp3.4 server returned project-a / RMCP_3_4_OK through the existing AIOS MCP client, with one fixture audit entry.
• All47 Connections tests passed; CLI and dashboard builds passed. The admission-only socket fixture and existing dashboard MCP add/list/test/remove, member/origin rejection and administrator-revocation checks passed against the final build.

No live service profile, tickets, grants or production configuration was changed. Harness diff remains empty. Backend changes are staged. Next is the client-facing MCP bridge, trusted Agent Mate ticket delivery/renewal/completion revocation, production-grade per-task isolation, and full unchanged-runtime acceptance. The current tests use a dedicated fixture workspace, not concurrent real projects or public-network tools.

Approved tool-schema discovery — 16 September 2026

Added a discover operation to the independent authority. It resolves the task ticket and exact executor route, starts the approved stdio upstream inside the isolated executor, and returns only currently approved names, descriptions and input schemas. No tool call is sent during discovery; starting an upstream can itself have side effects and remains subject to the existing isolation boundary. The authority re-resolves the ticket and current grants after the upstream responds. No ticket is forwarded to the executor. Discovery uses the same time/output bounds as execution and does not create execution receipts.

The final CLI build and both compiled fixtures passed. Tests observed navigate-only filtering, actual rmcp3.4 marker:string schema preservation, zero discovery tool invocations, rejection before upstream startup for another task or a removed grant, and withholding a response when the task ticket was revoked during discovery. Existing execution/isolation/replay/timeout and admission-only checks also passed. Evidence: scripts/blackboard/reports/mcp-tool-discovery.json; fixture: scripts/security/mcp-isolated-execution.py. Harness diff is empty. No live services or production configuration changed.

This completes schema discovery behind the authority, not the client-facing MCP server or automatic Agent Mate ticket handoff. Those remain pending. The official rmcp SDK is cached for fixtures but is not yet vendored into the AIOS workspace; adding it must preserve the repository’s offline build and desktop dependency union. Production-grade task containment and full unchanged-runtime acceptance remain required.

Linux and macOS parity — required for all AIOS additions

The user requires the complete AIOS functionality on Linux and macOS. This is not limited to the MCP bridge. No disabled macOS feature, Linux-only fallback, or reduced macOS feature set satisfies acceptance. The harness remains unchanged.

Implemented in the staged tree

• aios-task-platform is a library linked into AIOS and Agent Mate, not a new binary or agent engine.
• Repository publication now calls Linux renameat2(RENAME_NOREPLACE) or macOS renamex_np(RENAME_EXCL). The former explicit macOS error path is removed.
• The authority forwards MCP discovery and execution on both Linux and macOS; the CLI exposes executor/operation commands on both.
• Linux executor operations retain supervisor namespaces and no_new_privs/subreaper checks. macOS operations launch through native /usr/bin/sandbox-exec with a generated deny-by-default Seatbelt profile, selected workspace writes, explicit tool read roots, and no network grants. This implementation is not yet natively verified.
• Executor work and temporary directories are configured explicitly instead of assuming /work. Tool-runtime locations outside macOS system paths must be explicitly granted using --read-root; no dashboard home is copied or broadly exposed.
• Private file ownership and Unix socket peer credentials are shared OS transport protections. They do not replace account/task/project authorization.
• The official rmcp3.4 bridge is part of the existing AIOS executable. It reloads the private ticket per request, verifies authority UID, bounds protocol frames/authority requests, and derives durable call IDs from a runtime invocation namespace and MCP request ID. It never retries uncertain tool calls. Reuse the namespace for replay of the same invocation; generate a new one only for a new invocation. This is not automatic restart recovery.
• A fixture exposed an empty subprocess result. Explicit async stdout flush and cleanup-before-capacity-release are now in place; the final actual-tool and runtime fixtures passed.

Verification completed

The Linux CLI build passed. Four Agent Mate tests and four native-platform/policy tests passed. The real SDK bridge passed discovery, execution, duplicate/unapproved-call denial, renewal without restart, and task revocation. Two full turns through unchanged tui-backend passed: approved execution made one upstream call and completed; revocation after discovery made zero upstream calls and completed with denial. These use a network-isolated local fixture model and disposable keys, not a paid provider.

cargo check --tests -p aios-task-platform passed for both aarch64-apple-darwin and x86_64-apple-darwin. These checks cover the new platform library and native test code only. They are not a full Mac AIOS build or proof of native sandbox behavior. The repository's required vendor script preserved the workspace+desktop union and both metadata resolutions passed offline. No harness changes or production deployment occurred.

Remaining acceptance work — not waived

The reviewed dashboard HTTP/WebSocket gates, Connections storage and Agent Mate Unix socket identity paths have no explicit Linux-only branch in the inspected additions; they still require full native builds and behavior checks. This audit does not claim every pre-existing AIOS subsystem has been tested.

Source references for the implementation review: Apple SDK libc declarations for renamex_np/RENAME_EXCL; Tokio peer credential platform support; native Seatbelt policy example. Sandbox policy-construction tests are not a substitute for macOS execution.