RFC-001 — MCP Registry: discovery and execution of MCP servers

*uthor:*Koder Engineering *ate:*20260429 *tatus:*Accepted *odule:*servicesaimcp-registry *rigin:*koderstack ticket #031 (RFC017), OpenClaw analysis 20260429 *enamed from:*RFC-017 (namespaced convention for stack rfcs aggregation)

1. Summary

A Koder-hosted registry for MCP (Model Context Protocol) servers, modelled on the Hub for .kpkg packages. Developers publish MCP manifests; users discover and run them via kmcp; runtime execution goes through engines/sandbox (RFC-018) so each server is isolated with the same guarantees as any other untrusted-code surface.

2. Problem

MCP is the Anthropic protocol for connecting LLMs to tools. The Koder Stack's AI components (Kode, Kortex, Kanvas) all want to consume MCP tools, but there's no first-party way to:

1. Discover which servers exist
2. Verify a server's authorship and permissions
3. Run a server safely (no implicit trust)
4. Update servers as they evolve

Today every consumer either hard-wires a list of servers or relies on shell-installed binaries — neither scales beyond a handful of trusted authors.

3. Goals

• Public domain mcp.koder.dev lists every published MCP server.
• kmcp publish/install/list/run CLI mirrors the khub ergonomics.
• Each server runs in engines/sandbox (RFC-018) — declared

  permissions in the manifest map to sandbox capabilities.

• Auth + authorship via Koder ID v2.
• Audit log of installrun actions per `infraobserve/log`.

4. Non-Goals

• Replacing the MCP protocol itself. The registry consumes the existing

  Anthropic MCP spec; we are not extending the protocol.

• Hosting third-party MCP traffic. Servers run on the user's host (or a

  user-chosen remote sandbox); the registry only catalogs and ships manifests.

5. Manifest Format

MCP servers are distributed as .kpkg packages with a new top-level type = "mcp-server" (per specs/kpkg/format.kmd extension to be filed — coordinate with hubRFC006 #029 §6.5 which already added app|skill|bundle; this RFC asks for mcp-server to be added).

The kpkg.toml for an MCP server adds an [mcp] section:

[mcp]
spec_version = "0.6"           # MCP protocol version
transport    = "stdio" | "sse" | "http"
endpoint     = "/run/mcp.sock" # transport-dependent
tools        = ["read_file", "list_dir"]   # declared toolset
prompts      = ["summarise", "diagnose"]
sandbox_caps = ["fs:read:./data", "net:none"]

sandbox_caps declares the minimum permissions the server needs; kmcp run translates these to a sandbox.Spec with the matching Mounts and NetworkPolicy.

6. CLI

kmcp publish ./my-server.kpkg
kmcp install <slug>            # downloads .kpkg, verifies signature
kmcp list                      # local-installed
kmcp search <query>            # registry-wide
kmcp info <slug>               # show manifest
kmcp run <slug> [-- <args>]    # launches server in sandbox
kmcp logs <slug>               # tail audit log
kmcp uninstall <slug>

Per specs/binaries-and-cli/naming.kmd: binary kmcp, install dir /opt/koder/mcp/, D-Bus ID dev.koder.mcp.

7. Backend

services/ai/mcp-registry/depot/ — Go HTTP API at mcp.koder.dev/api/v1/. Same architecture pattern as Hub depot (kdb-next backend, multipart publish endpoint, kpkg storage). Mostly a smaller derivative of the Hub — we evaluated unifying the two but rejected (see §10).

8. Sandbox Integration

Every kmcp run invocation builds a sandbox.Spec from the manifest:

spec := sandbox.Spec{
    Image:   manifest.Image,            // optional — only if backend=docker
    Cmd:     manifest.RunCmd,
    Mounts:  capsToMounts(manifest.SandboxCaps),
    Network: capsToNetworkPolicy(manifest.SandboxCaps),
    Limits:  defaults(),
}
backend, _ := sandbox.Get(sandbox.Detect())
backend.Run(ctx, spec)

sandbox_caps is parsed by a small grammar:

• fs:read:<glob> → mount glob read-only
• fs:write:<glob> → mount glob writable
• net:none → NetworkNone
• net:loopback → NetworkLoopbackOnly
• net:egress:<host:port,…> → NetworkEgress with allowlist

Servers requesting more than declared at install time are killed.

9. Scope of Change

• services/ai/mcp-registry/ — new sector (this RFC + backend + CLI)
• specs/kpkg/format.kmd — extend type enum with mcp-server
• engines/sandbox — must be available (per RFC-018)
• engines/sdk/koder_kit — add MCP discovery client when consumers want

  to read the catalog from inside a Flutter app

10. Alternatives Considered

• *se the Hub registry directly.*Considered. The Hub already has

  publishinstallauth. Rejected because MCP consumption is fundamentally different (servers are executed, not installed), so the run-time story (sandbox integration, declared permissions, audit) belongs in a dedicated module.

• *se the public MCP server registry from Anthropic.*No such

  registry exists today. Even if one ships, a Koder-hosted mirror with Koder-side moderation and auth remains valuable.

• *kip the registry, ship MCP servers as ordinary .kpkg apps.*

  Rejected — apps are installed/launched by users; MCP servers are invoked transparently by other Koder agents. Different lifecycle.

11. References

• Anthropic MCP spec: https:/odelcontextprotocol.io/
• engines/sandbox/docs/rfcs/RFC-001-sandbox-architecture.md —

  required dependency

• hub-RFC-006 §6.5 — kpkg.type discriminator (this RFC asks for

  one more value)

• policies/sdk-first.kmd — kmcp is the canonical MCP entry point