registry-mcp

MCP client for the UluOps Registry API — 44 tools for definition management, analytics, and publishing.

Overview

MCP client for the UluOps Registry API. Browse definitions, fetch versions, publish updates, manage forks, and track effectiveness — all from Claude Code. Backed by @uluops/registry-sdk.

Installation

npm install @uluops/registry-mcp

This installs the uluops-registry-mcp binary. To install it globally instead, use npm install -g @uluops/registry-mcp.

Configuration

The server runs over stdio from npx, so the only things to set are the API key and, on native Windows, the launcher. Pick your platform — each block is ready to paste; replace ulr_your-api-key-here with a key from app.uluops.ai/settings/api-keys (see Setup → Your API key). This is the same entry npx @uluops/setup writes for you on macOS, Linux and WSL.

Where it goes (Claude Code): ~/.claude.json for every project on the machine (user scope), or .mcp.json in a repo root (project scope, shareable). On Windows the user-scope file is %USERPROFILE%\.claude.json. Other harnesses: OpenCode ~/.config/opencode/opencode.json, Gemini CLI ~/.gemini/settings.json, Codex ~/.codex/config.toml (TOML form below).

Linux / WSL

{
  "mcpServers": {
    "uluops-registry": {
      "command": "npx",
      "args": ["-y", "@uluops/registry-mcp"],
      "env": {
        "ULUOPS_API_KEY": "ulr_your-api-key-here"
      }
    }
  }
}

Or let Claude Code write it (user scope; keep an option between --env and the server name, or the CLI reads the name as another pair):

claude mcp add --env ULUOPS_API_KEY=ulr_your-api-key-here --transport stdio --scope user uluops-registry -- npx -y @uluops/registry-mcp

macOS

The JSON is identical to Linux. One macOS-specific gotcha: if Node comes from nvm or Homebrew and Claude Code was launched from the Dock rather than a terminal, it may not find npx on PATH. Use the absolute path (which npx) as the command:

{
  "mcpServers": {
    "uluops-registry": {
      "command": "/Users/you/.nvm/versions/node/v24.14.1/bin/npx",
      "args": ["-y", "@uluops/registry-mcp"],
      "env": {
        "ULUOPS_API_KEY": "ulr_your-api-key-here"
      }
    }
  }
}

PowerShell (native Windows)

On Windows npx is a .cmd shim, so stdio servers are launched through cmd /c. Set the key for the session or persist it for your user, then reference it in the config:

$env:ULUOPS_API_KEY = "ulr_your-api-key-here"                                        # this session
[Environment]::SetEnvironmentVariable("ULUOPS_API_KEY", "ulr_your-api-key-here", "User")  # persisted

{
  "mcpServers": {
    "uluops-registry": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@uluops/registry-mcp"],
      "env": {
        "ULUOPS_API_KEY": "ulr_your-api-key-here"
      }
    }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.uluops-registry]
command = "npx"
args = ["-y", "@uluops/registry-mcp"]

[mcp_servers.uluops-registry.env]
ULUOPS_API_KEY = "ulr_your-api-key-here"

If you installed the package globally (npm install -g @uluops/registry-mcp), "command": "uluops-registry-mcp", "args": [] works in place of npx on every platform. Restart the harness after editing the config.

The server connects to https://api.uluops.ai/api/v1/registry by default. Override with ULUOPS_REGISTRY_URL only if you're running a local or custom API instance.

Quick Start

// List all published agents
list_definitions({ type: "agent", status: "published" })

// Get a specific definition with YAML
get_definition({ type: "agent", name: "code-validator", include_yaml: true })

// Create and publish
create_definition({
  type: "agent",
  name: "my-validator",
  file_path: "my-validator.agent.yaml"
})
publish_definition({ type: "agent", name: "my-validator", version: "1.0.0" })

// Update and publish in one step
update_and_publish({
  type: "agent",
  name: "my-validator",
  version: "1.1.0",
  file_path: "my-validator.agent.yaml"
})

// Fork an existing definition
fork_definition({
  type: "agent",
  name: "code-validator",
  version: "3.2.0",
  new_name: "my-code-validator"
})

// Set a session default to avoid repeating type
set_default_type({ type: "agent" })

Tools Reference

Definition Management

Version Management

Forks and Lineage

Rendering and Execution

Analytics and Health

Models

Languages

Users

Response Field Filtering

All tools accept an optional fields parameter to filter response fields. This reduces payload size for large responses:

// Only return name, version, and status
list_definitions({ type: "agent", fields: ["name", "version", "status"] })

// Get just the health grade
get_health({ type: "agent", name: "code-validator", fields: ["grade", "score"] })

Pagination metadata (total, limit, offset, hasMore) is always preserved regardless of field filtering.

SDK vs MCP

Both access the same Registry API. Use MCP from Claude Code for interactive work. Use the Registry SDK for programmatic access in TypeScript applications and CI/CD pipelines.