Add capabilities without recompiling the runtime.

MHL owns orchestration and policy. Your executable owns the capability. The host starts one process on first use, reuses it for the run, multiplexes requests by id, and shuts it down at the end.

Install an extension under the project’s .mhl/extensions/<id> directory. A user-wide copy may live under ~/.mhl/extensions/<id>, but the project-local copy wins.

my-project/
├── main.mh
└── .mhl/
    ├── extensions.lock                 # explicit allow-list and hashes
    └── extensions/
        └── com.acme.crm/
            ├── extension.mh            # manifest and declarations
            └── bin/crm                 # executable

Define the extension in extension.mh, using MHL syntax. This file contains the manifest, properties, method signatures, and documentation. The manifest is read by mhl lint, the LSP, and extension diagnostics without spawning the process.

MINIMAL extension.mh

extensible crm {
    manifest: {
        id: "com.acme.crm",
        api_version: "1",
        executable: "bin/crm"
    }
}

The extensible <kind> declaration identifies the capability. Its manifest block requires id, api_version, and executable. Add version for a versioned package and permissions to describe its access requirements.

WITH TOOLING METADATA AND PERMISSIONS

A properties: { name: Type } block describes configuration, and bare name(params): ReturnType signatures describe methods — the return type follows :, exactly as on a tool method. The older name(params) -> ReturnType form still loads, but mhl lint rejects it. A leading /** ... **/ block documents the kind; a trailing /// ... documents a property or method through the end of the line. These documentation forms are recognized within the extensible declaration.

/**
Fetch a customer by id from the Acme CRM.
**/
extensible crm {
    manifest: {
        id: "com.acme.crm",
        version: "1.2.0",
        api_version: "1",
        executable: "bin/crm",
        permissions: {
            network: ["api.acme.com"],
            secrets: ["env(\"CRM_TOKEN\")"]
        }
    }

    properties: {
        endpoint: string /// The Acme API base URL.
    }

    lookup(id: string): object /// Fetch a customer by id.
}

Use the declared kind in a workflow

The kind connects an MHL declaration to your adapter. Properties and method signatures provide editor and lint metadata.

extension crm Customer {
    endpoint: env("CRM_URL")
}

Several installed adapters may serve the same kind. A declaration then names one by its manifest id with from; without it, a shared kind fails as ambiguous. A kind built into MHL (mcp, a2a) cannot be served by an external adapter.

extension crm Customer from "acme.crm.salesforce" {
    endpoint: env("CRM_URL")
}

Use one JSON object per line on stdout and stdin. There are no framing headers or batches. Lines larger than 8 MiB are rejected. Diagnostics belong on stderr, never in the JSON-RPC stream.

MESSAGE SHAPES

{ "id": 1, "method": "initialize",
  "params": { "api_version": "1", "host": "mhl", "host_version": "1.4.0-rc.2" } }

{ "id": 1, "result": {
  "api_version": "1",
  "extension": { "id": "com.acme.crm", "version": "1.2.0" },
  "declarations": []
} }

{ "id": 2, "method": "call", "params": {
  "declaration": { "kind": "crm", "name": "Customer", "props": [] },
  "operation": "lookup",
  "args": ["123"], "named_args": {}
} }

{ "id": 2, "result": { "id": "123" } }
{ "id": 2, "error": { "code": "not_found", "message": "..." } }

The extension process inherits no ambient environment beyond the host-provided extension variables and the manifest’s explicit env entries. Credentials are obtained only through secret.resolve and only when the manifest’s allow-list permits the exact reference.

{ "id": 7, "method": "secret.resolve",
  "params": { "reference": "env(\"CRM_TOKEN\")" } }

{ "id": 7, "result": "secret-value" }
{ "id": 7, "error": {
  "code": "denied", "message": "..."
} }

{ "method": "log",
  "params": { "message": "fetched 12 customers" } }

The CLI scaffolds the shape, exercises the protocol, captures declarations, and installs a pinned copy into a project — from a local directory, a git remote, or a published archive.

INSTALL FROM A REMOTE

# git — clone at a ref, optionally a subdirectory of a monorepo
mhl extension install https://github.com/acme/mhl-crm.git#v1.2.0
mhl extension install git@github.com:acme/monorepo.git//ext/crm#main

# archive — a .tar.gz / .zip published to a release (what `make release` emits)
mhl extension install https://github.com/acme/mhl-crm/releases/download/v1.2.0/mhl-crm.tar.gz
mhl extension install https://.../mhl-crm.tar.gz#sha256=<hex from SHA256SUMS>

A single string. For git: //subdir selects a directory inside the repo, #ref is a branch, tag, or commit; needs git on PATH. For an archive: the URL ends .tar.gz / .tgz / .zip, an optional #sha256=<hex> is checked against the download before anything is extracted, and the manifest is taken from the archive root or its single top-level directory. Both then follow the same copy → hash → pin path as a local install — the executable is never run.

LOCK ENTRY

{
  "extensions": {
    "com.acme.crm": {
      "version": "1.2.0",
      "sha256": "<hex sha256 of bin/crm>",
      "source": "git@github.com:acme/monorepo.git//ext/crm#main",
      "commit": "4a7d1ed414474e4033ac29ccb8653d9b1278fa8c"
    }
  }
}

source is set for any remote install (the git spec, or the archive URL including its #sha256=); commit only for git. A local-directory install writes just version and sha256, and an older lock without the extra fields still loads.

MULTIPLE PLATFORMS

One package can carry every platform's binary. Alongside the plain executable, drop a file per platform named <executable>-<goos>-<goarch> (…​-windows-amd64.exe on Windows) in the same directory — the extension.mh is unchanged, the plain name is just the stem. mhl extension install resolves the running host (the plain file if present, else the -<goos>-<goarch> one), vendors only that binary, and the lock pins its sha256; a host with no matching binary fails with the list of platforms the package does provide. A conventional package layout keeps a metadata-only tree (manifest + README, for lint / review) separate from a release build that adds the per-platform bin/ and a .tar.gz plus SHA256SUMS — all pure-Go, CGO_ENABLED=0.

An extension is ready to distribute when another developer can install it, inspect its permissions, and diagnose a failure without reading its implementation.