MCP server

Included from Basic tier

OpsChain as a Model Context Protocol tool server, shipped as a base capability: opschain mcp serve lets any MCP client — a desktop assistant, an IDE, an agent framework — query the estate, raise and follow changes and workflows, read events, chains, audit and evidence, and answer approvals, through a deliberately curated tool vocabulary.

The command is an API client, not a platform surface. It speaks MCP (JSON-RPC 2.0) to the assistant and the OpsChain API to the targeted server, holding no enforcement logic of its own: it cannot bypass an approval gate, cannot read what its principal may not read, and cannot suppress audit, because enforcement and audit happen server-side on every call exactly as for any other API caller.

Transports

• stdio — the local-assistant shape: the client launches opschain mcp serve as a child process; one JSON-RPC message per line on stdin/stdout, logs on stderr only.
• streamable HTTP — opschain mcp serve --http <addr> for hosted clients: messages POST to /mcp, each answered with a single JSON response. SSE streaming is not offered in this first cut; a client opening the stream (HTTP GET) is refused politely. TLS termination is the operator's reverse-proxy concern.

The handshake negotiates the protocol revision — 2025-06-18 preferred, older revisions accepted per the protocol's negotiation rule — and names the server and its version. Sampling and elicitation requests (a tool server asking the client's model or user for input) are always refused by name.

The tool vocabulary

A curated set of governed verbs, never a generated one-to-one dump of the API: each tool is a typed wrapper over one or two API calls, and its description carries the governance contract (creation may hold for approval; the tool returns the gate state, it never waits).

Group	Tools
Estate reads	list_projects, list_nodes, get_node, get_properties
Infrastructure	list_infrastructure, get_host
Change lifecycle	plan_change, create_change, get_change, get_change_logs
Workflows	run_workflow, list_workflow_runs, get_workflow_run
Events and chains	query_events, get_chain
Audit and evidence	query_audit, get_evidence
Approvals	list_my_approvals, answer_approval

The estate reads accept entity paths: get_node and get_properties read an entity like any other node, and list_nodes takes include_entities (with a root_path, which it then requires) to nest the entities under that subtree into the tree it returns.

Read tools carry readOnlyHint: true; mutating tools carry destructiveHint: true, honestly. Tools whose underlying surface the licence does not entitle (the evidence ledger without the packs:security-governance entitlement, the approvals inbox without a governance pack) are omitted from the tool listing for that server; execution re-checks regardless — listing is a courtesy, the API is the enforcement.

Authentication and audit

The credential is the CLI's ordinary token lane: --auth-token, or the stored login for the targeted server. For unattended assistant use, configure a dedicated service-account token so the assistant acts as a governed, individually attributable identity rather than as a person; a personal login is right when the assistant acts as you.

Every invocation is an ordinary API call through the existing request log and event lanes — nothing new to trust. The MCP tool name rides the client identification (opschain-mcp/<version> tool/<name> in the request's user agent), so the request log answers "which assistant verb did this" beside the principal.

Errors

Named refusals become MCP tool errors (isError: true) with the server's refusal text verbatim — an approval-policy hold, a validation violation or an entitlement lapse reads to the assistant exactly as it reads to a CLI user. Authorisation denials answer not found, exactly as the API answers them: denied and missing stay indistinguishable.

See also

• opschain docs cli/mcp-serve — the command manual: transports, flags, exit codes.
• opschain learn 12.9 — connecting Claude Desktop, an IDE or a hosted client, step by step.