> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acornops.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP registries

> Discover MCP servers from configured private, public, or air-gapped registries

AcornOps provides installation UX over registries that you configure; it does not operate its own catalog. No public registry is enabled by default. Self-hosted operators can bootstrap internal registries, and workspace admins can add registries when deployment policy permits.

Registries let administrators discover MCP servers without coupling a run to a live registry. AcornOps resolves and imports a pinned artifact onto one Agent or target installation. Runs use that stored snapshot even if the registry is later unavailable.

AcornOps supports the official MCP Registry v0.1 wire format at `/v0.1`. A private registry can expose the same format. Other formats require a compiled, allow-listed adapter; AcornOps does not execute uploaded adapter code or arbitrary JSON mappings.

## Discovery and installation

MCP registries and MCP installations have separate lifecycles:

1. An administrator adds or bootstraps a catalog source.
2. AcornOps synchronizes normalized artifacts, versions, digests, and compatible remote endpoints.
3. An administrator chooses an Agent or target destination and imports a pinned version onto that installation.
4. AcornOps discovers tools and leaves them disabled for review.
5. An administrator reviews each exact server/tool pair.

Package-only and stdio-only registry entries remain visible as incompatible. AcornOps v1 imports only remote Streamable HTTP endpoints.

| Destination | Entry point                                                                                 | Stored scope                                                                         | Available to                             |
| ----------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------- |
| One Agent   | **Agents → Agent detail → Capabilities → MCP servers → Add MCP server → Browse registries** | Exact workspace and Agent ID, with optional authoritative target type/ID constraints | Runs pinned to that Agent version        |
| One target  | **Target → MCP servers → Add MCP server → Browse registries**                               | Exact workspace and target ID                                                        | Runs through that target's default Agent |

Installing the same artifact on another Agent creates an independent installation. Each installation has its own server ID, endpoint configuration, enabled state, reviewed tools, provenance, pinned digest, connections, version history, and lifecycle. An installation never leaks to another Agent or target.

Browsing keeps the destination fixed and provides a canonical **Back to destination** link. Existing `/workspaces/:workspaceId/catalog` links remain valid, but destination-less visits require selecting an Agent or target before installation.

The same **Add MCP server** menu also provides **Connect by URL**. This accepts only the actual remote MCP Streamable HTTP endpoint, such as `https://mcp.internal.example/mcp`. It does not accept a registry URL, `server.json`, a GitHub repository, a package, a container, or a stdio command.

Workspace settings contain **MCP registries** administration. Authorized admins can also open it from **Manage registries** while browsing. Target installations and Agent installations remain independent even when they point to the same upstream URL.

## Managing registries

Admins with `manage_catalog_sources` can add, probe, edit, enable or disable, synchronize, and delete workspace-managed registries when deployment policy permits. Deployment-managed registries are configuration-read-only in the console, but authorized admins may synchronize them.

Enter an HTTPS registry root or path prefix, such as `https://registry.internal.example` or `https://platform.internal.example/mcp-registry`. Do not include `/v0.1`, query parameters, fragments, or credentials; AcornOps appends `/v0.1`. Credentials belong in the authentication fields. Only direct routing is currently available.

Disabling a registry immediately removes its artifacts from browsing but retains the cached snapshot for later re-enablement. Deleting a workspace registry removes its cache and registry credential. Neither operation uninstalls existing servers: installations retain pinned provenance and keep running, but cannot update until their source returns.

When no registry is configured, the browser offers **Connect by URL** and, for authorized admins, **Add a registry**. Other users are told to contact a workspace administrator.

## Agent and workflow permissions

Every workflow step selects exactly one Agent. The workflow can retain a subset of that Agent's MCP, skill, and tool grants or remove them; it cannot add a capability the Agent does not already grant. Target-owned installations remain available only through that target's default Agent and do not become workflow-owned credentials.

An empty workflow restriction grants no capability. It does not inherit all Agent permissions.

Runtime tool identity includes both the stable server ID and tool name. This keeps tools with the same name on different servers independently selectable and prevents name-only authorization.

## Credential ownership

Authenticated MCP installations explicitly select `workspace` or `individual`
credential ownership. Importing or enabling a server does not authorize it by
itself.

Workspace-managed credentials are installation-owned and can be used by user or
service principals. Individual credentials are scoped to one user and one
installation and require a user principal. Select the matching **Connect
credential** action, enter the write-only credential, and grant storage consent.
AcornOps stores it encrypted in the LLM gateway and immediately performs
authenticated tool discovery. Responses never return the secret or its name.

A target and an Agent always have separate connections, even for the same
upstream server. AcornOps never deduplicates connections by URL or copies
credentials between installations. Failed verification retains an encrypted
error-state credential so an authorized owner can verify, replace, or disconnect
it. An upstream `401` or `403` marks that exact connection erroneous.

## Kubernetes configuration

Configure registry policy under `components.llmGateway.catalog`:

```yaml theme={null}
components:
  llmGateway:
    catalog:
      officialRegistryEnabled: false
      # Set this only when deployment policy explicitly permits the public registry.
      officialRegistryUrl: https://registry.modelcontextprotocol.io
      allowWorkspaceManagedSources: true
      bootstrapSources:
        - workspaceId: "*"
          displayName: Internal MCP Registry
          baseUrl: https://registry.internal.example
          adapterBasePath: /v0.1
          networkRoute: direct
          enabled: true
          auth:
            type: bearer_token
            secretKeyRef:
              name: internal-registry-credential
              key: token
    mcpEgress:
      allowedHosts: registry.internal.example,mcp.internal.example
      allowPrivateNetworks: true
```

The chart renders a secret-free bootstrap JSON document. Each registry
`secretKeyRef` is injected into a separate environment variable and copied into
the configured gateway secret backend. Runtime MCP credentials are entered
through the console and have no Helm client or callback configuration.

## Air-gapped self-hosting

For a fully air-gapped deployment:

* set `officialRegistryEnabled: false`,
* bootstrap an internal v0.1-compatible registry,
* allow-list only internal registry and MCP server hostnames,
* mount your private CA through `components.llmGateway.mcpEgress.caBundle`, and
* keep all registry synchronization, artifact import, tool discovery, and runtime MCP traffic on the internal network.

No public internet access is required when the gateway, registry, and MCP servers share the private network.

Registry availability stays outside global platform readiness. Synchronization failures appear through each registry's status, bounded metrics, and structured logs.

## Agent-owned skills

Install manual or Git-backed skills from the same Agent **Capabilities** page. Git imports resolve to a pinned commit and content digest; upgrades require an explicit reimport. Skill installation state is independent on every Agent. The catalog layer reserves `agent_skill` as a later artifact handler, but MCP import never executes or installs skill content.

See [MCP and tools](/mcp-tools) for direct endpoint rules, tool review, and runtime behavior, and [Configuration](/configuration#mcp-egress-policy) for egress controls.