MCP_SCAFFOLDING.md

We are adding a new Harbor capability: Harbor-managed MCP launcher.

This is not an MCP proxy and not an MCP message rewriter. Harbor must not sit in the middle of normal MCP tool traffic. Harbor’s role is limited to:

cataloging MCP servers user-controlled enable/disable setup / remove / status lifecycle Docker-based launch and teardown audit logging local indexing of active MCP servers optional secret wiring from existing Harbor Ports into Docker Secrets

The goal is to let agents coordinate MCP availability through Harbor Node while keeping the user in control of permissions and visibility.

Product intent

A user should be able to:

browse/search a large MCP catalog in Hub see the same catalog mirrored in Node enable/disable individual MCP servers for their node allow an agent to request MCP setup through Harbor policy approve or deny setup requests see which MCP servers are active locally see who requested them, when they were added, their status, and recent lifecycle logs remove them cleanly

Example:

Agent1 requests Playwright, Fetch, Perplexity, SonarQube Node allows setup only for catalog entries not disabled by the user SonarQube secret may optionally be auto-wired from an existing Harbor Port into Docker Secrets Perplexity may require the user to provide a missing secret Harbor logs all setup activity and keeps a clean active list Harbor does not proxy actual MCP calls after setup Hard boundaries

Do not implement any of the following in this feature:

no MCP traffic interception no MCP request/response rewriting no generic credential vault redesign no non-Docker launcher backend in v1 no Kubernetes, Podman, systemd, or direct process runner in v1 no automatic harvesting of secrets from arbitrary locations no arbitrary shell launcher for untrusted agent input no “run any image from anywhere” behavior without catalog gating no silent auto-install of disabled catalog entries Required constraints Docker is the only launcher backend in v1 Docker Secrets are the standard secret delivery path Harbor Node owns lifecycle state and audit logs Hub/Cloud owns catalog metadata Node mirrors catalog metadata needed for local browsing and setup Community edition includes catalog browsing, enable/disable, setup request flow, approval/deny, lifecycle logging, active list, and remove Pro/Business may include automatic secret linking from existing Harbor Port hidden config into Docker Secrets Setup and remove must go through Harbor policy and audit Current Harbor Ports / Actions / Audit / UI patterns should be reused where it makes sense Avoid breaking existing Node, Hub, Cloud, SDK, and UI flows Keep the design simple, explicit, and extensible Architecture model Hub / Cloud responsibilities expose MCP catalog metadata support search/filter for catalog entries mark entries as available / deprecated / hidden if needed provide metadata needed by Node to render and launch safely Node responsibilities mirror or cache catalog metadata track per-node enabled/disabled state for catalog entries track installed/active MCP server instances manage Docker container lifecycle manage Docker Secret creation/linking where supported log all lifecycle events expose API for search, list, setup, remove, status, logs Agent interaction model agent asks Harbor to set up MCP server Harbor checks local enable/disable state and policy Harbor may require approval Harbor performs setup if allowed Harbor returns status / endpoint / launch metadata as appropriate agent then talks to the MCP server directly or through its normal configured path Harbor is out of the runtime call path after setup Initial terminology

Use mcp directly in API and UI naming for now.

Examples:

MCP Catalog Active MCP Servers MCP Setup Requests MCP Logs Catalog data model

Add a catalog entity for MCP server definitions. Keep it minimal and safe.

Suggested fields:

id slug name description publisher tags[] homepageUrl docsUrl image imageTagDefault transportType (stdio, http, https, mixed, unknown) launcherKind (docker) dockerImage dockerCommandTemplate? dockerArgsTemplate? defaultEnvSchema[] secretSchema[] portSchema[] volumeSchema[] healthcheckMode status visibility createdAt updatedAt

Important: keep templates declarative. Do not allow arbitrary agent-authored shell strings.

Node local state model

Add local persisted state for:

mcp_catalog_local catalogId enabled disabledReason? lastSeenCatalogVersion updatedAt mcp_instances id catalogId slug name status (requested, pending_approval, installing, active, degraded, failed, removing, removed) requestedByKind (operator, agent, script) requestedByName approvalState dockerContainerName dockerImage transportType connectionInfoSafeJson secretBindingMode (none, manual, port_linked) portLinkRefsSafeJson errorMessage? createdAt updatedAt lastStartedAt? lastStoppedAt? mcp_instance_logs id instanceId eventType level message detailsJsonSafe createdAt API surface

Add Node API endpoints under /v1/mcp.

Prefer REST even if internal action names use shorthand like mcp.search.

Cloud API GET /v1/mcp/catalog GET /v1/mcp/catalog/search GET /v1/mcp/catalog/:catalogId Node API GET /v1/mcp/catalog GET /v1/mcp/catalog/search POST /v1/mcp/catalog/:catalogId/enable POST /v1/mcp/catalog/:catalogId/disable GET /v1/mcp/instances GET /v1/mcp/instances/:instanceId POST /v1/mcp/setup POST /v1/mcp/instances/:instanceId/remove GET /v1/mcp/instances/:instanceId/logs GET /v1/mcp/instances/:instanceId/status

Optional:

POST /v1/mcp/instances/:instanceId/restart POST /v1/mcp/refresh-catalog Policy model

Introduce policy concepts for:

mcp.setup mcp.remove mcp.enable mcp.disable mcp.restart

Keep policy aligned with Harbor’s existing allow / deny / require_approval pattern.

Community vs Pro/Business Community browse/search catalog local enable/disable setup requests approval flow docker launch/remove lifecycle logs active instance list status inspection Pro/Business optional secret auto-linking from existing Harbor Port hidden config into Docker Secrets saved secret templates / mappings maybe richer indexing/search/filter analytics maybe automated setup suggestions

Do not overbuild licensing. Just put clean feature gates in the right seams.

UI requirements Hub

New MCP page/section:

searchable MCP catalog filters catalog detail clear “available in Harbor Node” messaging Node

New MCP tab/page:

catalog mirror list enable/disable toggle active instances list setup requests status badges logs table with search/filter one-click setup from allowed catalog entries visibility into missing secrets / approval needed / current status Audit events

Add audit coverage for:

catalog viewed catalog searched catalog entry enabled catalog entry disabled setup requested setup approved setup denied setup started secret linked secret missing docker launch succeeded docker launch failed instance status changed remove requested remove succeeded remove failed Docker constraints use Docker SDK or existing Node shell abstraction carefully deterministic container naming deterministic secret naming labels on containers to identify Harbor ownership safe cleanup behavior safe idempotency on repeated setup/remove never log secret values do not expose secret values in safe config responses Secret-linking behavior

This is optional and gated.

If an MCP server has a required secret that maps cleanly to an existing Harbor Port hidden config, Harbor may create or attach a Docker Secret during setup.

Examples:

SonarQube token from an existing SonarQube Port future Perplexity key from a compatible existing Port

This must be:

explicit auditable never dump raw values into logs safely absent in Community if not licensed Delivery style

Work in milestones. Keep each milestone scoped and shippable. Update docs as you go. Preserve current architecture and conventions. Run build/typecheck/tests where appropriate after every milestone.

Milestone 1 prompt — contracts, docs, and scaffolding

Add the base Harbor MCP launcher scaffolding with minimal risk.

Deliverables architecture/design note for Harbor-managed MCP launcher shared contract types for MCP catalog entries, local enable/disable state, instances, logs, statuses placeholder Cloud and Node route registration placeholder UI nav/tab wiring for Hub and Node MCP pages docs updates describing scope and non-goals Requirements do not yet implement Docker launch do not yet implement secret linking add types and route stubs only keep current build green update README, API surface docs, and workflow docs Acceptance criteria project builds MCP page/tab exists in Hub and Node as placeholder API routes compile and return stub responses shared SDK/types are in place docs clearly state that Harbor manages setup/status only, not MCP runtime traffic

Milestone 2 prompt — Cloud MCP catalog

Implement the Hub/Cloud side MCP catalog.

Deliverables Cloud API endpoints for MCP catalog list/search/detail seed or fixture support for a catalog sized for hundreds of entries catalog filtering/search support Hub UI MCP catalog page catalog detail view Requirements use static seeded catalog data first design for future sync/import, but do not build sync engine yet expose only safe metadata needed by Node/UI support tags, publisher, transport, launcher kind, status clean search and filter UX Acceptance criteria Hub shows MCP catalog search/filter work catalog detail page works Cloud API returns typed responses no Docker logic in this milestone

Milestone 3 prompt — Node local catalog mirror and enable/disable

Implement Node-side mirror/cached catalog state and per-node enable/disable.

Deliverables Node persistence for local catalog state Node API endpoints for local catalog list/search and enable/disable Node UI for MCP catalog mirror enable/disable toggles per catalog entry audit events for enable/disable Requirements catalog entries disabled locally cannot be set up by agents preserve a clear distinction between global catalog metadata and local node state keep UX simple add filters for enabled/disabled/all Acceptance criteria Node shows mirrored catalog operator can enable/disable entries disabled entries are clearly marked audit logs record toggles project builds and tests pass

Milestone 4 prompt — setup request flow and MCP instance lifecycle state

Implement MCP setup request flow and local active instance registry, but still without real Docker launch.

Deliverables POST /v1/mcp/setup GET /v1/mcp/instances GET /v1/mcp/instances/:instanceId approval-aware policy handling for mcp.setup instance state persistence Node UI for active MCP instances Node UI for setup requests / pending approval / status badges audit coverage for request/approval/deny/state changes Requirements if catalog entry is disabled locally, reject setup if policy says approval required, create pending instance/setup request state simulate lifecycle transitions cleanly do not yet start Docker containers Acceptance criteria agent/operator/script can request setup instance records appear in Node UI approval/deny flow works status transitions are visible and auditable still no runtime MCP traffic proxying

Milestone 5 prompt — Docker launcher backend

Implement Docker-based MCP launch/remove/status for Harbor-managed instances.

Deliverables Docker launcher service abstraction setup path creates deterministic Harbor-managed container remove path removes container and updates state status path inspects container health/runtime state instance logs capture lifecycle steps labels and naming conventions for Harbor-owned containers Requirements Docker is the only launcher backend use declarative catalog metadata only do not allow arbitrary user/agent shell injection idempotent setup/remove safe cleanup on failure do not log secrets add clear error handling for missing Docker / pull failure / launch failure Acceptance criteria setup can launch a supported catalog entry into Docker remove cleans it up status reflects real container state failures are visible in instance logs and audit current Harbor features remain unaffected

Milestone 6 prompt — Node MCP logs and filtering UX

Build the Node MCP operations view so users can actually manage this cleanly.

Deliverables Node MCP page polish active instance table lifecycle logs table filters for agent, catalog entry, status, event type search detail drawer/page for one instance Requirements make it easy to answer: what is active now who asked for it why did it fail what needs approval what was removed match Harbor UI style and existing tables/patterns Acceptance criteria Node MCP page is usable without docs logs are searchable/filterable instance detail is readable approval-needed and failure states are obvious

Milestone 7 prompt — optional secret linking from existing Ports

Implement paid-gated secret auto-linking from compatible Harbor Ports into Docker Secrets.

Deliverables secret mapping model lookup of compatible existing Port hidden config Docker Secret creation/attachment path clear gating for Pro/Business audit events for linked/missing secrets UI messaging for missing secret vs linked secret docs for the feature and limitations Requirements do not redesign Harbor secrets globally only support explicit, schema-based mappings never reveal raw secret values in API/UI/logs if mapping not available, surface a clean missing-secret state keep Community behavior intact without this feature Acceptance criteria compatible Port hidden config can be linked into Docker setup path paid gating works at the feature seam failures degrade cleanly logs and audit remain safe

Milestone 8 prompt — Cloud/Hub to Node one-click flow

Connect the Hub MCP catalog experience to Node setup flow in a clean, non-breaking way.

Deliverables Hub catalog entries can deep-link or hand off to Node consistent terminology across Hub and Node simple flow for “view in Hub, set up in Node” docs and UI copy polish Requirements keep Hub and Node responsibilities distinct do not add direct Cloud-side launch keep Node as the authority for local setup/state Acceptance criteria user can discover in Hub and act in Node easily flow is clear and not confusing docs match actual behavior

Milestone 9 prompt — SDK and programmatic agent support

Expose the MCP management surface through the Harbor SDK and agent-facing docs.

Deliverables SDK methods for catalog search, enable/disable, setup, remove, list instances, status, logs agent workflow docs describing how agents should request MCP setup examples for: requesting a setup handling approval required checking active instances removing when done Requirements keep the SDK aligned with existing Harbor patterns do not imply Harbor proxies runtime MCP calls document that the agent uses Harbor to prepare capability, then uses MCP normally Acceptance criteria SDK compiles docs are concrete and copy-paste useful examples match actual API behavior

Milestone 10 prompt — hardening and cleanup

Do a hardening pass across the full MCP launcher feature.

Deliverables edge-case fixes idempotency fixes migration cleanup docs cleanup test coverage where feasible better empty/loading/error states final API surface review Requirements verify no secret leakage in logs or safe responses verify disabled catalog entries cannot be launched verify approval flows are enforced verify Docker launcher cleans up safely preserve existing Harbor architecture Acceptance criteria build/typecheck pass docs are coherent MCP feature feels native to Harbor no accidental drift into proxying MCP traffic Extra implementation notes for Codex Recommended file areas to touch shared contracts / SDK package Cloud API route registration and handlers Node API route registration and handlers Node store / persistence layer Node Docker integration service Hub UI page and components Node UI page and components docs: README, API surface, workflow docs, MCP-specific docs Suggested docs to add docs/mcp-managed-launcher.md docs/mcp-policy-and-lifecycle.md docs/mcp-secret-linking.md Good defaults deterministic instance slugging deterministic Docker labels soft-delete or removed-state record retention for logs/history safe JSON blobs for future extensibility explicit status enums, not freeform strings Non-goal reminder

Harbor is a control plane for MCP availability, not a transport proxy.

Very short single-shot prompt version

Use this if you want one broad Codex pass first:

Add a Harbor-managed MCP launcher feature to the existing monorepo. Harbor must manage MCP catalog discovery, local enable/disable, setup/remove/status lifecycle, Docker-based launch, active instance tracking, and audit logging. Harbor must not proxy or rewrite MCP runtime traffic. Docker is the only launcher backend in v1. Hub/Cloud should expose MCP catalog metadata. Node should mirror catalog state, enforce local enable/disable and policy, manage Docker lifecycle, and expose /v1/mcp endpoints. Community edition includes catalog, toggles, setup/remove/status, active list, and logging. Pro/Business may optionally auto-link compatible existing Harbor Port hidden config into Docker Secrets during setup. Add Hub and Node MCP pages, SDK support, docs, and acceptance-quality scaffolding in milestones without breaking existing Harbor architecture.