MCP server

orbitalreg-mcp-server exposes your Agent/Skill package registry to any Model Context Protocol client — Claude Desktop, an IDE agent, a CI assistant — so an AI agent can find, inspect and download the skills your organisation has approved, instead of pulling arbitrary code off the public internet.

It is a client-side binary. It runs on the developer's machine, is spawned by their MCP client, speaks JSON-RPC 2.0 over stdin/stdout, and listens on no port. It is not deployed into your cluster and has no chart template.

What it can and cannot do

The server is read-only, and deliberately thin: every tool is an authenticated proxy over the registry's ordinary HTTP API. It does not talk to the database, the object store or the pull-gate engine directly. That is the whole security argument — a package an agent pulls through MCP passes exactly the same pull gate, security blocks, license policy and audit logging as one pulled by curl, because it is the same request path. There is no MCP-specific code to keep in sync with the real one, and so no MCP-specific bypass to get wrong.

It cannot publish, promote, delete, or change any configuration. If you want an agent to publish, use a service-account token with the normal API.

Install

Download the signed release archive for your platform from the project's releases (tags shaped mcp/v*.*.*), or build it yourself:

make mcp-server-build      # -> bin/orbitalreg-mcp-server

Verifying a release

The SHA256SUMS manifest is signed with cosign keyless, so the signing identity recorded in the Rekor transparency log is the release workflow ref — not a long-lived key we hold. Pin both the identity and the issuer when verifying; omitting either makes the check meaningless, because any Sigstore-issued certificate would satisfy it:

cosign verify-blob \
  --certificate-identity-regexp '^https://github\.com/orbitalreg/orbitalreg/\.github/workflows/mcp-server-release\.yml@refs/tags/mcp/v' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  --signature orbitalreg-mcp-server_<version>_SHA256SUMS.sig \
  orbitalreg-mcp-server_<version>_SHA256SUMS

Then check the archive against the manifest with sha256sum -c.

Configure a client

Every MCP client takes the same three pieces of information: the command to run, the registry URL, and a token. Claude Desktop's claude_desktop_config.json looks like this; other clients use the same shape with a different filename.

{
  "mcpServers": {
    "orbitalreg": {
      "command": "/usr/local/bin/orbitalreg-mcp-server",
      "env": {
        "ORBITALREG_MCP_API_BASE_URL": "https://registry.example.com",
        "ORBITALREG_MCP_TOKEN": "orbr_..."
      }
    }
  }
}

A container image is published as a convenience for clients configured to run servers under Docker:

{
  "mcpServers": {
    "orbitalreg": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "ORBITALREG_MCP_API_BASE_URL",
        "-e", "ORBITALREG_MCP_TOKEN",
        "ghcr.io/orbitalreg/orbitalreg-mcp-server:latest"
      ],
      "env": {
        "ORBITALREG_MCP_API_BASE_URL": "https://registry.example.com",
        "ORBITALREG_MCP_TOKEN": "orbr_..."
      }
    }
  }
}

-i is required and -t must be absent. The protocol is a raw byte stream on stdin/stdout, and a TTY's line discipline corrupts it.

Get the config pre-filled

The Connect an MCP client panel on any agentskill repository page in the web UI renders both snippets with your own registry URL already substituted, ready to copy.

Environment variables

Variable	Default	Meaning
ORBITALREG_MCP_API_BASE_URL	http://localhost:8080	Registry origin.
ORBITALREG_MCP_TOKEN	(required)	An orbr_… personal token or orbsa_… service-account token. Sent as Authorization: Bearer.
ORBITALREG_MCP_HTTP_TIMEOUT	30s	Go duration string.
ORBITALREG_LOG_LEVEL	info	debug, info, warn, error.

Choosing a token

Prefer a project-scoped service-account token (orbsa_…). Project scope is enforced at the wire protocol, so the MCP client can reach only that project's repositories — a personal token carries all of your own access into the agent's hands. Issue one under the project's Service accounts tab.

Tools

Tool	Arguments	Returns
list_skills	query (required), limit (1–50, default 20)	Matching packages, via the registry's trigram search restricted to format=agentskill. A non-empty query is required — the underlying search endpoint returns nothing for an empty one rather than enumerating the registry.
get_skill	project_slug, repo_slug, name (required), version	The full manifest: kind, declared tools/permissions/egress/dependencies, the SKILL.md description, and a download URL. version defaults to latest, meaning most-recently-uploaded — not SemVer-highest.
get_policy_status	artifact_id (required)	Scan completion and open findings by severity, plus whether an active security block matches.
pull_skill	project_slug, repo_slug, name (required), version	The package tarball, base64-encoded as a resource block (application/gzip), capped at 64 MiB — the format adapter's own publish limit. Oversized responses are rejected, never silently truncated.

Two known gaps in get_policy_status

Both are documented limits of the underlying endpoint rather than bugs in the MCP layer, and are worth knowing before you build a policy on the output:

• Only sha256-type security blocks are evaluated. Blocks by path, pattern, package or auto-CVE are not reflected in the response. A package can therefore report clean here and still be refused at pull time — which is the safe direction to fail, but it means this tool is not a substitute for attempting the pull.
• Signature status is always unknown. Verify-on-pull runs at download time and its result is not persisted per artifact, so there is nothing to report.

Logging

Diagnostics go to stderr as structured JSON, tagged with the mcp_server component. stdout carries only the JSON-RPC stream; anything else written there would corrupt the protocol. If you are debugging a client that shows no tools, run the binary by hand with ORBITALREG_LOG_LEVEL=debug and watch stderr.