Registry↗Dashboard↗

ops-mcp

MCP server for the UluOps Platform API — 55 tools, 2 resources.

Overview

MCP client for the UluOps Platform API. Provides 55 tools and 2 resources for the tracker: runs, issues, the project log, analytics — zero business logic, pure protocol translation.

Installation

bash
npm install @uluops/ops-mcp

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

ℹ
Note

Naming note — this one server wears a different name at each layer. The npm package is @uluops/ops-mcp; it installs a binary named uluops-ops-mcp; the recommended .mcp.json server key is uluops-tracker (that key is what produces the mcp__uluops-tracker__* tool names in Claude Code); and in prose we call it the Tracker. All four refer to the same component. The separate @uluops/registry-mcp (uluops-registry) server is a different thing — see MCP Clients.

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

json
{
  "mcpServers": {
    "uluops-tracker": {
      "command": "npx",
      "args": ["-y", "@uluops/ops-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):

bash
claude mcp add --env ULUOPS_API_KEY=ulr_your-api-key-here --transport stdio --scope user uluops-tracker -- npx -y @uluops/ops-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:

json
{
  "mcpServers": {
    "uluops-tracker": {
      "command": "/Users/you/.nvm/versions/node/v24.14.1/bin/npx",
      "args": ["-y", "@uluops/ops-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:

powershell
$env:ULUOPS_API_KEY = "ulr_your-api-key-here"                                        # this session
[Environment]::SetEnvironmentVariable("ULUOPS_API_KEY", "ulr_your-api-key-here", "User")  # persisted
json
{
  "mcpServers": {
    "uluops-tracker": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@uluops/ops-mcp"],
      "env": {
        "ULUOPS_API_KEY": "ulr_your-api-key-here"
      }
    }
  }
}
ℹ
Note

The Linux and macOS blocks are what @uluops/setup writes and are exercised daily. The Windows block follows the standard cmd /c npx pattern for stdio MCP servers but has not yet been exercised on a Windows machine by us — if it misbehaves, run cmd /c npx -y @uluops/ops-mcp in PowerShell with the key set and send us the first lines it prints.

Codex (~/.codex/config.toml)

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

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

If you installed the package globally (npm install -g @uluops/ops-mcp), "command": "uluops-ops-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/ops by default. Override with ULUOPS_BASE_URL only if you're running a local or custom API instance.

VariableDescriptionRequired
ULUOPS_API_KEYAPI key — must start with ulr_, min 20 charsYes
ULUOPS_BASE_URLBackend API URLNo (default: https://api.uluops.ai/api/v1/ops)
ULUOPS_TRACKER_TIMEOUTRequest timeout in msNo (default: 30000)
LOG_LEVELLogging levelNo (default: info)

Quick Start

typescript
// Save a validation run
save_run({
  project:       "my-project",
  workflow_type: "ship",
  agents: [{ name: "code-validator", score: 85, decision: "PASS" }],
  recommendations: [{
    agent: "code-validator",
    title:     "Fix lint error",
    priority:  "suggested",
    failure_code: "STR-MAL/M"
  }]
})

// Query open critical issues
query_issues({ project: "my-project", status: "open", priority: "critical" })

// Get project summary with issue counts and trends
get_project_summary({ project: "my-project" })

Tools Reference

Runs

ToolDescription
save_runSave validation pipeline output with fingerprint-based issue correlation. Supports analysis_summary, analysis_records, and exploration_maps for structured agent output.
update_runUpdate run metadata post-hoc — add tokens, scores, recommendations, or analysis data after initial save
validate_runPreview what save_run would do without writing to the database
preview_update_runPreview an analysis-bearing update_run under the requested record_write_mode. Reports, per agent named in the payload, what the write would supersede, create, and — under replace — retire by omission (wouldRetireRecordIds; always empty under merge, which cannot retire). Nothing is written
get_runGet a run by UUID
get_run_detailsRun info with all recommendations, correlation stats (new/recurring/regression). Omit run_number for latest
get_run_analysisGet structured analysis records and summaries for a run — convention inventories, tension maps, system metrics
get_latest_runGet the most recent run for a project, optionally filtered by workflow type
list_runsList runs for a project with pagination
diff_runsCompare two runs — fixed, new, unchanged issues, and agent score changes
delete_runDelete a run (requires confirm: true)
archive_runsArchive old runs without deletion — by run number, date, or keep-last count

Issues

ToolDescription
query_issuesQuery issues by project, status, priority, agent, severity, failure domain/mode, persistence
search_issuesFull-text search across projects with relevance ranking and multi-filter support
create_issueCreate a user-submitted issue directly, outside of validation runs
get_issue_detailsFull issue lifecycle with occurrences, notes, regression history, and optionally related issues
get_issue_historyComplete issue history — all occurrences, changes between runs, and notes
get_issue_by_fingerprintLook up an issue by its SHA-256 fingerprint
update_statusUpdate issue status — identify by ID, fingerprint, or file_path+title
update_issue_by_fingerprintUpdate issue status by fingerprint
bulk_update_statusUpdate multiple issue statuses in one transaction (max 100)
undo_issue_statusUndo the last status change on an issue
edit_issueEdit issue metadata (title, file_path, category, severity, failure_code) without changing fingerprint
add_issue_noteAdd context, resolution, or blocker notes to an issue
merge_issuesMerge duplicate issues into a target — migrates occurrences, marks sources as merged
soft_delete_issueSoft-delete an active issue. Sets deleted_at; reversible via restore_issue
restore_issueRestore a soft-deleted issue

Projects

ToolDescription
list_projectsList all active projects (excludes soft-deleted)
get_projectGet project by ID or name with metadata, run count, and issue stats
create_projectCreate a new project for tracking
update_projectRename a project
get_project_summaryProject overview with workflow stats, agent performance, and issue counts
get_project_trendsIssue trends over time for a project
soft_delete_projectSoft-delete a project (can be restored). Requires confirmation
restore_projectRestore a soft-deleted project with all associated data
delete_projectPermanently delete all project data. Two-step confirmation required
rehome_projectMove a project and its whole history (runs, issues, analytics) into another org. org is the source, target_org the destination; admin/owner in both. Reversible by moving it back
get_project_logThe project's second history: runs (what was examined) and decisions (what was decided, with reasons) interleaved, newest first, plus what came back. One keyset-paged page of run / decision / regression events — the same read as ulu log
get_log_statThe log's rollup for a window: examined / found / decided (current status, completed = fixed) / cameBack (caught by a run vs reopened by decision) / activity. Project, or the resolved org with a per-project table — ulu log --stat / --orgs
merge_projectsMerge one project into another: runs and issues are re-keyed into the target, colliding issues deduplicated by fingerprint, and the source soft-deleted. Pairwise only — chain calls to consolidate several. Run dry_run: true first; the merge is durable with no undo

Analytics

ToolDescription
get_analyticsCross-project analytics: agent_performance, resolution_rates, cross_project_patterns, file_hotspots, regression_analysis, trend_summary, cost_analysis, taxonomy_distribution
get_agent_reliabilityAgent effectiveness — false positive rates, resolution rates, reliability scores
get_agent_matrixAgent-taxonomy coverage matrix with blind spot detection and overlap analysis
get_agent_lifecycleVersion lifecycle trajectory for an agent — performance per definition version
get_agent_runs_analysisAnalysis summaries with run context for a specific agent across runs
get_burndownTaxonomy burndown with time series and trend analysis per failure domain
get_velocityVelocity metrics per failure mode with sparkline data and trend reliability
get_discoveryDiscovery timeline — new vs recurring issues over time

Taxonomy

ToolDescription
get_taxonomyGet the failure taxonomy schema (domains, modes, severities)
get_full_taxonomy_analyticsDistribution analytics by domain, severity, mode, and agent

Analysis Records

ToolDescription
get_project_analysisAnalysis summaries for a project — system metrics, category scores, epistemic assessments from cognitive lens runs
query_analysis_recordsQuery analysis records across all projects — find calcified conventions, degraded tensions, decay vectors, and other structured findings
list_agentsList canonical agents accepted by save_run

Organizations

ToolDescription
get_org_audit_feedAn org's member-visible audit feed — today, projects that left the org for someone's personal org (who, when, where to). Any member may read it

Account

ToolDescription
update_profileUpdate the authenticated user's profile (username, name, bio, timezone, websiteUrl). Setting a username confirms it one-time and is required before creating or publishing registry definitions

Resources

Resource URIDescription
validation://projectsList all tracked projects (JSON array)
validation://taxonomyFailure taxonomy schema — domains, modes, severity codes

Resources vs Tools — For project-specific data, use the get_project_summary tool rather than resources. MCP resource templates with parameters are not fully supported by the current SDK.

Issue Statuses

Issues support seven resolution statuses:

StatusMeaning
openActive, unresolved
completedGenuine defect, fixed
wontfixCorrect observation, not worth acting on (lifecycle mismatch)
false-positiveAgent was factually wrong
observationValid observation, tracked separately from defects
deferredAcknowledged, deferred to later
mergedMerged into another issue

Rate Limiting

Configured for Claude Code's burst-then-pause usage pattern:

SettingValue
maxRequestsPerMinute120
burstThreshold15
burstWindowMs5000
automationDetectiondisabled
OperationTypical Parallel Calls
Query context (summary, issues, runs)3–5
Create issues from validation workflow10–30
Update agents with metrics6
Save recommendations1 (array payload)

Why automation detection is disabled — Claude Code is trusted automation with consistent timing patterns. Enabling bot detection would misidentify legitimate agent use as suspicious traffic.