interfaces

What it is

URI

majordomus://feature/interfaces

Kind

feature

Identity

interfaces

Path

.ai/repo/features/interfaces.md

Provenance

declared

Media type

text/markdown

As a capability

feature.interfaces

Front matter

{
  "schema": "feature/v1",
  "id": "interfaces",
  "kind": "feature",
  "title": "One registry over the command line, HTTP, OpenAPI, Swagger UI and MCP",
  "short_title": "Interfaces",
  "headline": "Every agent, script and person reads the same repository through the interface it already speaks, and none of the interfaces is maintained by hand.",
  "summary": "The Rust executable serves the layer read-only over stdio MCP, MCP over HTTP, routes under /api/v1/, an OpenAPI document with a Swagger UI, and a command line, all derived from the capability registry; one shared server per repository, and every attached client is a peer the others can see.",
  "status": "stable",
  "weight": 20,
  "domain": "surfaces",
  "featured": false,
  "areas": [
    "documentation",
    "observability",
    "coordination"
  ],
  "modules": [
    "repository",
    "objects",
    "web",
    "environment",
    "executions",
    "commands",
    "editors",
    "entity",
    "mcp"
  ],
  "rules": [
    "project.web-surface-declared-once",
    "project.web-surface-topology",
    "project.native-cli-documented",
    "project.shared-server-resilience"
  ],
  "docs": [
    "docs/MCP.md",
    "docs/WEB.md",
    "docs/CAPABILITIES.md"
  ],
  "adrs": [
    "adr-0001",
    "adr-0003",
    "adr-0013"
  ],
  "claims": [
    "mcp-stdio-surface",
    "mcp-data-driven",
    "mcp-shared-server",
    "mcp-lease-resilience",
    "mcp-peers",
    "mcp-client-autostart",
    "mcp-uri-resolution",
    "openapi-inferred",
    "web-surface-declared-once",
    "web-namespaces-reserved",
    "cli-documentation-executable"
  ],
  "use_cases": [
    "serve-the-layer-to-ai-clients",
    "see-what-the-repository-holds-without-reading-it",
    "find-an-object-without-reading-everything"
  ],
  "cockpit": [
    "api"
  ],
  "web": [
    "api",
    "openapi",
    "swagger",
    "mcp",
    "docs",
    "rustdoc"
  ],
  "related": [
    "declare-once",
    "coordination"
  ],
  "tags": [
    "mcp",
    "http",
    "openapi",
    "cli"
  ]
}

Content

---
schema: feature/v1
id: interfaces
kind: feature
title: One registry over the command line, HTTP, OpenAPI, Swagger UI and MCP
short_title: Interfaces
headline: Every agent, script and person reads the same repository through the interface it already speaks, and none of the interfaces is maintained by hand.
summary: The Rust executable serves the layer read-only over stdio MCP, MCP over HTTP, routes under /api/v1/, an OpenAPI document with a Swagger UI, and a command line, all derived from the capability registry; one shared server per repository, and every attached client is a peer the others can see.
status: stable
weight: 20
domain: surfaces
featured: false
areas: [documentation, observability, coordination]
modules: [repository, objects, web, environment, executions, commands, editors, entity, mcp]
rules: [project.web-surface-declared-once, project.web-surface-topology, project.native-cli-documented, project.shared-server-resilience]
docs: [docs/MCP.md, docs/WEB.md, docs/CAPABILITIES.md]
adrs: [adr-0001, adr-0003, adr-0013]
claims: [mcp-stdio-surface, mcp-data-driven, mcp-shared-server, mcp-lease-resilience, mcp-peers, mcp-client-autostart, mcp-uri-resolution, openapi-inferred, web-surface-declared-once, web-namespaces-reserved, cli-documentation-executable]
use_cases: [serve-the-layer-to-ai-clients, see-what-the-repository-holds-without-reading-it, find-an-object-without-reading-everything]
cockpit: [api]
web: [api, openapi, swagger, mcp, docs, rustdoc]
related: [declare-once, coordination]
tags: [mcp, http, openapi, cli]
---

## What it does

The first `majordomus mcp` in a repository binds one shared server on the loopback
interface and logs every surface it serves: the home page, this documentation, the crate's
rustdoc, the Cockpit, the Swagger UI, the OpenAPI document, the capability routes and MCP
over HTTP. Every later client attaches to it instead of starting another, and the server
ends when its last client leaves. The client configurations at the repository root — one
per provider that reads one, as `docs/generated/providers.md` lists them — name one
launcher, so opening the repository in any of them is enough.

What the server answers is the registry: a tool, a resource, a route or a command exists
because a declaration exists, and the same declaration is what the reference and the
website render. A surface — the documentation mount, the crate's rustdoc, a generated
report, the Swagger UI — is discovered from the thing that produces it, or from the source
that says it exists, and resolved once into a topology the router, the home page, the
publication and the validator all read.

## What it does not do

Almost nothing here writes to the repository: all but two of the capabilities over MCP and
HTTP are reads, and most of the commands that change anything change only this process's
memory. The exceptions are named rather than implied — `plan.transition` and
`recover.orphans` — and the `initialize` instructions every client reads name them too,
counted off the registry rather than stated by hand, because a sentence that promises a
read-only surface is exactly the sentence an agent acts on. There is no
authentication and no remote binding by default; the server is for the clients on this
machine. It does not run a model and it does not route work to one.