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.
- The plugin protocol is MCP, using the official
mcpSDK (§3.6): mcp-stdiofor local plugins: the core starts the plugin as a subprocess from an argument list (no shell);mcp-http(streamable HTTP) for remote services.- Any MCP server can become a plugin by adding a
plugin.yamlmanifest. - The core calls tools explicitly from pipeline steps. There is no LLM tool selection (ADR 0001).
- Permissions are declared in the manifest (
network,secrets,paths,intents) and enforced in two tiers: - M1–M4, "declared": one subprocess per plugin, a clean environment with only its declared secrets, outputs checked against declared intents;
- M5, "isolated": one container per plugin on an
internal: truenetwork, egress only through an allow-listing proxy built frompermissions.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:
runtimeis{ 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 inpermissions.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-briefwithout 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
httpsformcp-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.pathsare 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.