agentregistry Documentation

When using the MCP Registry v0.1 compatibility layer, be aware of the following behaviors:

• RBAC and Scoping: The endpoint reuses the native ListFilter and Authorize hooks. In the OSS build, these are not wired, meaning the catalogue is flat and unfiltered across all namespaces. In builds where crud.PerKindHooks for MCPServer are wired, the same RBAC/tenancy scoping applies.
• Anonymous Access: Routes under the compatibility shim are registered as public paths. They bypass credential authentication and use an auth.PublicSession. Presented tokens are ignored; every caller sees the same catalogue defined by the ListFilter/Authorize hooks.
• Version Support: Only the v0.1 spec is supported. The legacy v0 API is not served.
• Field Mapping: http package transports are surfaced as streamable-http with synthesized URLs (e.g., http://localhost:<port><path>). Server versions are derived from package origins (npm/pypi/OCI) or fall back to 0.0.0.

Models are admin-owned resources that define provider identity, endpoints, and authentication.

Harness Deployments: A harness Agent Deployment can explicitly select a Model using modelRef:

modelRef:
  name: claude-opus-4-8
  tag: approved-v1

Default Model Behavior:

• If modelRef is omitted from a harness Agent Deployment, the registry resolves Model/<deployment namespace>/default@latest.
• Important: Platform administrators should create a Model named default in each namespace to avoid spec.modelRef dangling-reference errors. The registry does not automatically pick the first available model.
• Non-harness Agent and MCPServer Deployments do not receive an implicit Model.

spec:
  targetRef:
    kind: Agent
    name: summarizer
  runtimeRef:
    kind: Runtime
    name: agentcore
  harness:
    type: claude-code
  modelRef:
    name: claude-opus-4-8
    tag: approved-v1

AgentRegistry follows Semantic Versioning (SemVer):

• Major (X.0.0): Breaking API or behavior changes.
• Minor (X.Y.0): Backward-compatible features.
• Patch (X.Y.Z): Backward-compatible fixes.

Tagging Conventions:

• Git tags and container image tags use a leading v (e.g., v0.4.0).
• Helm chart versions omit the v prefix (e.g., 0.4.0).

Published Artifacts for version vX.Y.Z:

• Container Images (Linux amd64 and arm64):
  • ghcr.io/agentregistry-dev/agentregistry/server:vX.Y.Z
  • ghcr.io/agentregistry-dev/agentregistry/arctl-agentgateway:vX.Y.Z
• CLI Binaries: Available for Linux (amd64, arm64), macOS (amd64, arm64), and Windows (amd64).
• Helm Chart: Located at oci://ghcr.io/agentregistry-dev/agentregistry/charts/agentregistry (Chart version X.Y.Z, App version vX.Y.Z).
• GitHub Release: Contains release notes, CLI files, the packaged Helm chart, and a checksum file.

The Helm chart deploys several Kubernetes resources depending on your configuration:

The registry supports registering MCP packages from npm, pypi, and oci. The registry validates ownership by comparing the serverName in the manifest against the identity embedded in the upstream artifact.

Configuration Structure:

• spec.source.package.origin.type: One of npm, pypi, or oci.
• spec.source.package.origin.identifier: The canonical address (e.g., image ref for OCI, package name for npm/PyPI).
• spec.source.package.launch: (Optional) Overrides default launch commands (command, args, env). If omitted, the resolver uses defaults like npx -y <pkg>@<ver> for npm or uvx <pkg>==<ver> for PyPI.

Handling Naming Mismatches: If the upstream identity (e.g., reverse-DNS namespace/name) cannot be used as the local metadata.name, use a local DNS-1123 subdomain for metadata.name and provide the full upstream identity in spec.source.package.origin.<type>.serverName.

# Example: Registering an npm package with a custom upstream identity
apiVersion: ar.dev/v1alpha1
kind: MCPServer
metadata:
  name: mcp-fetch                                                # local catalog name
spec:
  source:
    package:
      origin:
        type: npm
        identifier: "@modelcontextprotocol/server-fetch"
        npm:
          version: 0.1.0
          serverName: io.github.modelcontextprotocol/server-fetch  # upstream identity
      transport:
        type: stdio

AgentRegistry acts as the central catalog for MCP servers, agents, and skills. It pairs with agentgateway to provide a secure, unified entry point for AI clients (like Claude Desktop, Cursor, or VS Code).

The Workflow:

1. Curation: Platform teams publish approved artifacts to AgentRegistry.
2. Deployment: When you run arctl apply -f deployment.yaml, AgentRegistry automatically configures the agentgateway routing.
3. Consumption: Instead of configuring clients for every individual MCP server, clients connect to a single agentgateway endpoint.
4. IDE Integration: Use arctl configure cursor (or similar commands for other IDEs) to point your development environment at the gateway endpoint.

Key benefits of the gateway approach:

• Single Endpoint: One URL for all tool calls.
• Security: Centralized JWT validation and access policies.
• Observability: Unified OTEL logging/tracing for all agent-to-tool traffic.
• Dynamic Discovery: New servers in the registry are automatically available to connected clients without reconfiguration.