Reference host · OpenAI4S

One host path. One evidence ledger.

The host is where an agent meets the contract. OpenAI4S is the reference host: it discovers endpoints, opens least-privilege sessions, surfaces mode and risk, obtains approvals and records every receipt.

Normative mappingMHS-Host profileMCP-first, verified

Integration paths

Zero-patch MCP today, native tools next

The integration design deliberately separates an interoperability proof from the first-class host path. Both speak the same contract; neither changes the endpoint.

Read the integration design

MCP

Primary integration — MCP projection

The SDK ships a stdio MCP server (python -m mhs.mcp). It is registered as an ordinary OpenAI4S connector; tools are generated from bound capabilities and every call goes through OpenMHS sessions, permits and receipts.

mcp.json

// OpenAI4S connector settings — one ordinary MCP connector per endpoint
{"connectors": [{
  "id": "mhs-lab",
  "command": ["python3", "-m", "mhs.mcp",
              "--endpoint", "http://127.0.0.1:7401"],
  "transport": "stdio",
  "enabled": false          // experimental: off until the operator enables it
}]}

The endpoint owns sessions, permits and receipts. MCP only supplies the tool seam.

dev

Optional developer overlay

A stdlib overlay registers the same host surface as native tools for CLI debugging. It is not required for host conformance and is gated by the same experimental switch.

install

# Optional developer overlay (not the integration path; same switch)
PYTHONPATH=MHS/sdk/src:integration/openai4s python3 -c   "import openai4s_mhs as m; m.install(m.MHSConfig(enabled=True))"
python3 -m openai4s_mhs devices --endpoint http://127.0.0.1:7400

mhs__devices / mhs__inspectDiscover endpoints and fetch full device manifests with mode, risk and fidelity gaps.
mhs__readRead a resource revision and state hash.
mhs__<device>__<capability>One tool per bound capability, device-scoped; returns a receipt (rejections included).
mhs__permitRequest a single-use permit bound to the exact input digest.
mhs__safety / mhs__estop / mhs__resetRead status, latch the e-stop, reset once interlocks are clear.
mhs__operationsInspect or cancel an operation without blocking the loop.
mhs__evidenceExport and verify the hash-chained evidence bundle.

The one-call property

The same code path for every endpoint

No per-repository branches in the host. The differences live in the adapter plane: a Rust conveyor, a Python simulator, a MuJoCo arm or a microscope all arrive through the same client.

Host profile

openai4s_one_call.py

from mhs import connect

with connect("mhs://localhost:7400") as lab:              # one transport
    dev = lab.devices[0]                                   # one discovery
    receipt = lab.invoke(                                  # one command
        "cap.world.step.v1", {"ticks": 120}, device_id=dev["device_id"])
    state = lab.read("workcell")                           # one read
    evidence = lab.export_evidence()                       # one ledger
    print(receipt["status"], receipt["state_hash_after"], evidence["head_digest"])

Architecture

Four planes, one loop

The host owns policy, approvals and the ledger. The endpoint owns enforcement. The adapter owns translation. The equipment is never trusted to interpret intent.

Host

OpenAI4S

Agent loop, tools, policy, approvals and the evidence ledger.

Binding

JSON-RPC

stdio, HTTP/SSE, WebSocket, MCP projection, CLI and code API.

Contract

OpenMHS endpoint

Sessions, commands, receipts, safety envelope, revisions and evidence chain — enforced by the endpoint.

Adapter / equipment

Manifest and bridge

Declarative mapping to a driver, SDK, simulator or protocol.

Evidence

The ledger is not optional

A host that records only successes cannot explain a refusal or an unknown outcome. Every receipt is appended, chained and exportable.

Evidence chain specification

hash chain

receipt_i.evidence.digest =
    sha256( JCS(receipt_i \ { evidence }) || receipt_(i-1).evidence.digest )

genesis = endpoint genesis record
head    = digest of the latest receipt
verify  = recompute the chain offline; no endpoint trust required

Receipts, including refusals

Accepted, failed, rejected and unknown outcomes are all receipts. A policy refusal is evidence of the envelope working, not an exception to log away.

Offline verification

The bundle carries receipts, endpoint metadata and the head digest. A verifier re-derives the chain without trusting the endpoint.

Redaction is declared

Adapters declare redaction rules for credentials and PII. Evidence must not contain secrets; telemetry travels by reference, not by copy.

Retention

Receipts are retained for at least 30 days by default and are not deletable through the protocol without a truncation marker.

Experimental MCP connector

Off by default, enabled by the operator

OpenMHS is an experimental MCP integration: the connector rows are listed in settings but disabled, so no projected tool and no endpoint connection exist until a human turns the feature on. Enabling is an explicit, recorded operator action.

HOST-066…069

settings

# experimental MCP integration — connector rows are listed, disabled by default
python3 -m openai4s_mhs status    # {"kind": "mcp", "enabled": false, "experimental": true}
python3 -m openai4s_mhs mcp-config --json
#   -> {"connectors": [...], "enabled": false, "transport": "mcp"}
python3 -m openai4s_mhs enable    # operator action: flips the connector rows + settings on
python3 -m openai4s_mhs disable   # and back off again

# while disabled:
#   - the MCP connector is not activated; no projected mhs__* tool is reachable
#   - no endpoint connection is opened by the feature
#   - the rows stay visible in settings with "enabled": false so a human can turn them on
# enabling is the same switch for MCP and for the optional developer overlay.

Experimental — not a default capability

Installation, upgrade, endpoint discovery or first launch never enable MHS. The switch is an explicit operator action recorded in settings (and in OpenAI4S's capability state as skill/mhs).

Default off, fail closed

While disabled the host registers no mhs_* tool, emits no MCP connector and opens no endpoint connection. The model is not told that OpenMHS exists.

MCP companion

Enabled, the same switch exposes both surfaces: native tools for code-as-action and an stdio MCP connector per endpoint for a generic MCP harness.

Operator tooling stays explicit

The python3 -m openai4s_mhs CLI remains available to a human for diagnostics, but it is never auto-invoked by the agent.

Host requirements

What MHS-Host actually requires

A host is conformant on behaviour, not intent. These are the obligations from the host profile, including the experimental-surface rules (HOST-066…069).

Discover endpoints from every configured source and authenticate them.
Open least-privilege sessions and refresh or close them correctly.
Obtain approvals before calling capabilities that require a permit.
Present mode, fidelity gaps, risk class and trust level to the model.
Enforce deadlines and cancellation; never retry an unknown outcome blindly.
Record every receipt in an append-only evidence ledger; export and verify it.
Never claim or imply that OpenMHS replaces hardware safety.
Expose capabilities through MCP tools, native tools or a code API, with schemas in sync.

OpenAI4S mapping

Where each responsibility lives

The overlay package sits beside OpenAI4S; the only patch is tool registration. The MCP fallback avoids even that.

Component	Responsibility
`openai4s_mhs/config.py`	Settings: `enabled` (default `false`), endpoints, hardware gate, evidence log; atomic 0600 writes.
`openai4s_mhs/experimental.py`	Records the experimental `skill/mhs` capability in OpenAI4S's own capability store so the switch is visible in settings.
`openai4s_mhs/host.py`	`MHSHost`: discovery, least-privilege sessions, permits, evidence ledger, mode and fidelity disclosure, hardware gate.
`openai4s_mhs/tools.py`	Eight native tools + dispatcher wiring, installed only when enabled; disabled install registers nothing.
`openai4s_mhs/mcpconfig.py`	MCP companion: one stdio connector per endpoint (`mhs.mcp`), emitted only while the skill is enabled.
`mhs.mcp`	MCP projection of any OpenMHS endpoint; OpenAI4S's existing `MCPManager` needs no host change.

MCP is the integration seam

MCP standardises how a model reaches tools; OpenMHS standardises what a tool that moves matter means — mode, units, limits, interlocks, receipts and evidence. The projection maps each bound capability into an MCP tool and maps refusals back to structured OpenMHS codes; sessions, permits and the safety envelope stay inside the endpoint, outside the model.

Try the endpoint playground Read the host profile