Skip to content

ADR 0003: MCP as the plugin protocol

  • Status: Accepted
  • Date: 2026-10-27 (proposed)
  • Accepted: 2026-10-28

Context

Plugins provide sources, sinks, notifiers, skills, transforms and pipeline packs (§3.1). They must be able to run as separate processes (so that each gets only its declared secrets, and later its own container), be written in any language, and reuse the existing personal services that already speak MCP (§3.3, §6).

Decision

Horae plugins are MCP servers, and the core calls their tools explicitly from pipeline steps.

  1. The plugin protocol is MCP, using the official mcp SDK (§3.6):
  2. mcp-stdio for local plugins: the core starts the plugin as a subprocess from an argument list (no shell);
  3. mcp-http (streamable HTTP) for remote services.
  4. Any MCP server can become a plugin by adding a plugin.yaml manifest.
  5. The core calls tools explicitly from pipeline steps. There is no LLM tool selection (ADR 0001).
  6. Permissions are declared in the manifest (network, secrets, paths, intents) and enforced in two tiers:
  7. M1–M4, "declared": one subprocess per plugin, a clean environment with only its declared secrets, outputs checked against declared intents;
  8. M5, "isolated": one container per plugin on an internal: true network, egress only through an allow-listing proxy built from permissions.network, only declared paths mounted, read-only filesystem, non-root.

The contract is schemas/plugin-manifest/v1.json, generated from src/horae/contracts/plugin.py:

  • runtime is { protocol: mcp-stdio, command: [...] } or { protocol: mcp-http, url: https://… }, and is optional for plugins that only ship skills or pipelines;
  • for mcp-http, the URL host must be in permissions.network (checked by the model only);
  • permissions default to empty: no access.

Consequences

Positive

  • Language-agnostic plugins, and existing MCP services plug in through a manifest or plugin-mcp-brief without being rewritten (§5).
  • Process boundaries make secret scoping possible from M1 and container isolation possible in M5 without changing the protocol.
  • The same protocol serves Horae's own read-only MCP server (with approval-gated pipeline.run, §3.5).

Negative

  • Until M5, enforcement is "declared": a subprocess can still reach hosts or paths it did not declare. That is acceptable for first-party plugins only.
  • MCP spec and SDK churn can break the plugin host. Mitigation: pin the SDK and keep the host behind an internal interface (§10).
  • A subprocess per plugin costs memory and start-up time on small servers.

Open questions

  • The v1 contract accepts only https for mcp-http, including internal Docker or Coolify service names (decision 6 in the schemas README). Existing services joined over a Docker network (§7) therefore need TLS; whether that is practical is unverified. Container-name stability across Coolify redeploys is a ⚠️ spike in §7.
  • What permissions.paths are relative to (container, instance root, vault mount) is open (decision 9).
  • How a tool namespace (coach.brief) resolves to a plugin is for the engine to define (decision 11).
  • Default runtime after M5 (containers for third-party plugins only, or all) is open (§11 item 2).

Alternatives considered

  • Python packages loaded in-process (the pip-package model of §1). Simplest to call, but Python-only and no process boundary for secrets or isolation.
  • A custom JSON-RPC or HTTP protocol. Full control, but no ecosystem; existing services would need adapters.

References