Skip to main content
Publish and manage registry components. The registry has five component types: MCP servers, skills, hooks, prompts, and sandboxes.

Subcommand structure

Every component type also supports archive, unarchive, ownership transfer, and co-author management. Registry also contains the models, version, recommend, and mixed bulk groups. All registry references accept a UUID, canonical namespace/slug, a unique legacy bare name, a row number from the latest human list output for the same component type, or an @alias. Agents and scripts must use returned UUIDs or qualified_name values, never row numbers. If the same bare slug exists in multiple namespaces, qualify it, for example alice/search instead of search.

Fork an approved component

The five fork commands accept SOURCE [--name NAME] [--version BASE] [--new-version V] [--team HANDLE|UUID] [--visibility public|team] [--output table|json]. Only currently approved sources and approved base versions are eligible. The fork is a separate editable draft, not a new release of the original; it has its own namespace, owner, reviews, and installation identity. Team-private sources can only be forked within their teamspace. JSON returns the direct server draft object. Edit using observal registry <type> edit FORK_UUID ... and submit through that type’s draft workflow. show prints visible fork provenance and the count of public approved direct forks. If source access is lost, it displays Source unavailable rather than the saved source reference. A private or unpublished fork never increases the public count.

Shared lifecycle and collaboration commands

Archive, restore, and ownership transfer require explicit confirmation in JSON mode. Their JSON output is the direct server result. Co-author list returns the standard list envelope; add and remove return the direct server result. The namespace is the publisher’s username or a teamspace handle. Usernames cannot change after the account owns a registry listing. Team members can browse approved private teamspace items in normal list results. Use --team TEAM_HANDLE to include public items plus that team’s private items, or --namespace TEAM_HANDLE to restrict results to that namespace. Direct references use team-handle/item-slug. Nonmembers receive the same not-found response for private items as for unknown items.

Teamspace visibility

Use the teamspace target and visibility options on submit commands:
public teamspace items are visible to all registry users. team items are visible only to team members and privileged reviewers. Team owners and reviewers can change visibility after publication. A team member’s new submission still follows the normal review workflow.

Mixed bulk submission

Submit up to 200 MCP, skill, hook, prompt, and sandbox entries from one JSON file:
The file is a bare array or an object with a components array. Each entry contains type plus the normal API submission fields:
Dry run validates file structure without contacting submission endpoints. Execution structurally validates every entry before the first mutation, submits entries in order, reports conflicts as skipped, and returns per-entry IDs, canonical names, review status, and safe errors. Results include partial; item errors set it to true and exit with code 11, while conflicts counted as skips remain successful. Authentication, permission, rate-limit, version, and service failures stop the batch. JSON execution requires --yes. Re-running a partially completed file is safe only after inspecting results. Existing identities are skipped for component types that reject duplicates. Verify created items by returned UUID or qualified_name.

MCP servers

MCP server registry commands for submitting, browsing, generating configuration, editing, and archiving MCP server listings.

observal registry mcp submit

Submit an MCP server to the registry. By default, paste your server’s JSON config (the same format you use in your harness). Use --git to analyze a git repository instead.

Synopsis

Options

Default flow (JSON paste)

  1. Prompts you to paste your MCP server JSON config.
  2. Accepts multiple formats:
    • harness config: {"mcpServers": {"name": {"command": "...", "args": [...], "env": {...}}}}
    • Bare config: {"command": "npx", "args": ["-y", "pkg"]}
    • SSE/HTTP: {"url": "http://...", "type": "sse", "headers": {...}}
    • server.json manifest: {"packages": [...], "remotes": [...]}
  3. Auto-detects environment variables from $VAR patterns and env keys.
  4. Shows a config preview and prompts for metadata (name, description, category).
  5. Submits to registry for review.

Git analysis flow (--git)

  1. Shallow-clones the repo.
  2. Detects the MCP framework (FastMCP, MCP SDK, TypeScript SDK, Go SDK).
  3. Extracts server name, description, and exposed tools via AST.
  4. Scans for required env vars (os.environ, os.getenv, .env.example, server.json).
  5. Prompts for metadata confirmation.
  6. Submits to registry for review.

Examples

Valid categories

browser-automation, cloud-platforms, code-execution, communication, databases, developer-tools, devops, file-systems, finance, knowledge-memory, monitoring, multimedia, productivity, search, security, version-control, ai-ml, data-analytics, general.

Valid transports

stdio, sse, streamable-http.

Valid frameworks

python, docker, typescript, go.

observal registry mcp list

List approved MCP servers in the registry.

observal registry mcp my

List your own MCP servers across all statuses (draft, pending, approved, rejected).

observal registry mcp show

Show full details of an MCP server including validation results, env vars, and supported harnesses.

observal registry mcp install

Generate a harness config snippet for an MCP server. This command does not write harness configuration or record an installation. Interactive mode prompts for required environment variables and headers. JSON mode requires --no-prompt and rejects missing required values before config generation with error.result.needs_input: true.

observal registry mcp edit

Edit an MCP server submission. For draft/pending/rejected listings, edits in place. For approved listings, publishes a new version with a semver bump.
Without flags, opens an interactive JSON paste prompt (same format as submit).

observal registry mcp transfer-owner

Transfer ownership to another username. You stop being the owner immediately.

observal registry mcp sync

Publish a new MCP version automatically when the listing’s GitHub or GitLab repository changes. See Sync an MCP server from GitHub or GitLab for the full setup. On an existing setup, enable keeps any setting you do not pass.

Skills

Skill registry commands. Skills are portable SKILL.md instruction packages that provide agents with task-specific guidance. Valid task types: code-review, code-generation, testing, documentation, debugging, refactoring, deployment, security-audit, performance, general.

observal registry skill submit

Submit a new skill for review. Provide --git-url to let the server fetch SKILL.md automatically, or use --skill-md to paste content directly.

observal registry skill list

List approved skills in the registry.

observal registry skill my

List your own skills across all statuses (draft, pending, approved, rejected).

observal registry skill show

Show detailed information about a skill, including validation status, task type, git source, and slash command.

observal registry skill install

Install a skill by fetching the full skill directory from git. Clones the skill directory via sparse checkout and writes it to the appropriate harness skill path.
Scopes:
  • user (default): writes to ~/.<harness>/skills/<name>/ globally.
  • project: writes to .agents/skills/<name>/ in the current directory, then symlinks into detected harness config directories.
JSON output does not disable installation. It returns whether files were written and the installed path. Raw and no-write modes do not record the skill as installed. An installed skill is recorded with its exact version, version id, and digest, with or without --version. A failed file write or lockfile update returns a categorized failure instead of reporting success.

observal registry skill edit

Edit a draft, pending, or rejected skill submission. Acquires an edit lock to prevent concurrent modifications.

observal registry hook submit

Submit a new hook for review. Supports inline script content via --script, or git-hosted hooks via --source-url.

observal registry hook list

List approved hooks from the registry.

observal registry hook show

Show detailed information for a single hook, including event type, handler config, and execution mode.

observal registry hook install

Install a hook for a specific harness. Writes script files and merges hook config into the harness’s settings. Existing hooks are preserved during merge.
Hook installation validates every path before writing, refuses to replace malformed existing JSON, writes files atomically, and does not duplicate an existing event entry when repeated. The lockfile records the installed version, its version id and digest, and any version you requested.

observal registry hook edit

Edit a draft, pending, or rejected hook submission. Acquires an edit lock to prevent concurrent modifications.

observal registry prompt submit

Submit a new prompt template for review. You can submit interactively, from a JSON file, or from a raw template file.
If --from-file points to a non-JSON file, its content is used as the template and you are prompted for metadata interactively.

observal registry prompt list

List approved prompts in the registry.

observal registry prompt my

List your own prompts across all statuses (draft, pending, approved, rejected).

observal registry prompt show

Show detailed information about a prompt, including the template content.

observal registry prompt render

Render a prompt template with variable substitution. Sends key=value pairs to the server, which substitutes them into the template and returns the rendered output.

observal registry prompt edit

Edit a draft, pending, or rejected prompt submission. Acquires an edit lock to prevent concurrent modifications.

observal registry sandbox submit

Submit a new sandbox environment for review.

observal registry sandbox list

List approved sandboxes in the registry.

observal registry sandbox show

Show detailed information about a sandbox, including runtime type, container image, and resource limits.

Sandboxes are attached to agents by UUID and are installed when the agent is pulled. There is no standalone Sandbox install command.

observal registry sandbox edit

Edit a draft, pending, or rejected sandbox submission. Acquires an edit lock to prevent concurrent modifications.

Component versions

Use observal registry version publish and observal registry version list for all five component types. Publication supports direct JSON results; history supports explicit pagination. See observal registry version for the complete contract.

Personalized recommendations

Use observal registry recommend to rank visible components against the signed-in user’s sessions and to dismiss or mark recommendations as installed. See observal registry recommend for the JSON schema and feedback actions.