Pre-release Harn is pre-1.0 — the language, standard library, and CLI may change between releases. See the release notes

ADR 0003: use the official Rust MCP SDK

Status#

Superseded on 2026-08-02. Harn now uses rmcp 3.1 for MCP client lifecycle, stdio transport, framing, request association, standard metadata, version negotiation, and typed protocol errors.

The previous decision kept a hand-written implementation because rmcp 1.7 did not model the proposed 2026 protocol. The revisit condition recorded by that decision has occurred: MCP 2026-07-28 is stable, and rmcp 3.1 supports it together with the released 2025 and 2024 protocol versions.

Decision#

The official SDK owns commodity MCP protocol behavior:

  • server/discover and legacy initialize lifecycle selection;
  • protocol-version negotiation for 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, and 2024-11-05;
  • JSON-RPC framing, IDs, response association, cancellation, and bounded shutdown for child-process clients;
  • stable error codes, method names, capabilities, request metadata, standard HTTP headers, MRTR types, and task types.

Harn continues to own product policy and host integration:

  • VM values and builtin return shapes;
  • egress and SSRF policy, OAuth state, capability fixtures, and audit records;
  • roots, elicitation, sampling, and progress routing;
  • workflow dispatch, task execution, authorization, and server persistence.

The boundary is the SDK handler and transport adapter, not a second protocol model. Harn constants that must be emitted into generated bindings are checked against rmcp's typed registry.

Compatibility#

The default client uses the stable discovery lifecycle and prefers 2026-07-28. It negotiates another SDK-supported released version when a discovery-capable peer requires one. When a peer proves it is legacy by returning Method not found for server/discover, the SDK performs the 2025-11-25 initialize/initialized handshake.

The former rc and explicit legacy modes were removed. Compatibility fallback is available only where the SDK provides it as part of its standard automatic lifecycle.

Consequences#

The raw stdio client framing, request-ID loop, response drain, lifecycle probe, and child shutdown code have been deleted. Stable task names and result shapes replace the draft tasks/list, tasks/result, nested task envelope, and execution.taskSupport fields.

Harn's HTTP client and server adapters still contain Harn-owned authorization, request streaming, and dispatch policy. They use the SDK registry as their protocol oracle; moving more of those adapters behind SDK transports is appropriate only when it preserves Harn's egress, OAuth, audit, cancellation, and streaming contracts without duplicating them.

Evidence#

  • protocol_registry_matches_official_sdk checks Harn's public version and error-code projections against rmcp.
  • The MCP compatibility suite exercises stable discovery, standard headers, MRTR, task polling, and both Harn server surfaces; SDK-owned tests exercise released-version negotiation and the older stdio lifecycle.
  • The canonical Harn stdio client test runs discovery over a real child-process transport owned by rmcp; released-version fallback remains covered by the SDK that implements it.

See the MCP and ACP integration reference for the public configuration contract.

Edit this page on GitHub