@opvs-ai/mcp

@opvs-ai/mcp

OPVS MCP server for the on-demand model — 16 tools that give any MCP host (Claude Desktop, Cursor, Antigravity, Windsurf, Claude Code) the same surface OPVS-hosted agents see: 10 always-on marketplace tools, sandbox_chat (a vendor test mode), and 5 fleet tools for machines and slots. Everything else is reached through tool_call indirection so the package fits under the ~100-tool cap every current MCP client enforces.

Tool	Wraps	Purpose
tool_search	registry /search	Semantic search by intent (absent/cold/warm/hot telemetry signal)
tool_help	registry /packages/{vendor}/{name}	Methods + manifest on demand
tool_read	registry /packages/{vendor}/{name}/skill-guide	Read any published skill's actual SKILL.md + references/ layers on-demand, nothing installed (path pulls one layer file)
tool_call	/marketplace/runtime/{install_id}/{skill}/{method}	Universal proxy — manifest.skills[].id routing
tool_pin	gateway skill_pin (see "tool_pin status")	Pin/unpin a skill into an OPVS agent's TOOLS.md
tool_list_installed	/marketplace/installed	What this brand has
tool_install	/marketplace/packages/{id}/install	Add a package with explicit consent
tool_uninstall	DELETE /marketplace/installed/{id}	Remove a package
whoami	/auth/me	Session probe — brand, agent, workspace
board_as_markdown	/board/boards/{id}/export?format=md	A whole AgentBoard as a Markdown plan in one call (detail summary/standard/full, columns filter)

Fleet — machines and slots

The environment layer had no agent-reachable surface at all until these landed, so "dashboard or MCP" was dashboard-only. They are native tools rather than tool_call routes for the same reason board_as_markdown is: there is no marketplace skill for environments, so there is no schema.yaml to route through.

Tool	Wraps	Purpose
fleet_list	/environments + /environments/allowance	Every slot this brand owns + the machine allowance it spends, grouped by machine. detail compact/full
slot_get	/environments/{ref} → /workstations/{uuid}	One slot + its per-step onboarding checklist, and next_action — the single step to act on
slot_health	/environments/{ref}/health	Live sidecar probe (reaches the box over WireGuard)
fleet_logins	/environments/credentials/reauth-status	Lapsed logins on both credential lanes, reported separately
slot_order	POST /workstations	Order a slot — writes: spends the allowance, mints a one-shot install PAT

Vocabulary

At the product surface there are exactly two nouns, and the tool names use them (MACHINE-AND-SLOT.md §3, owner ruling 2026-09-07):

• MACHINE — the physical host. What a tunnel terminates at. Keyed by machine_id.
• SLOT — the worker at a desk on it. What a card is claimed by, what a terminal opens into.

On the wire it is still environments, and that disagreement is deliberate — renaming a live table, its router and its TS type buys nothing a reader needs. The words box and desk are retired from new writing but appear throughout the older docs. Every tool description names the synonyms, so an agent told "list my environments" or "check my box" still finds the tool.

Three things that surprise people

• Any ref shape works on slot_get and slot_health. Full UUID, an 8-or-more hex prefix, or the env_… short code. slot_get resolves the ref first and then uses the canonical UUID for the checklist hop — because /workstations/{id} accepts only a UUID and 404s a short code, which would otherwise read as "your slot does not exist".
• A null is never a green light. allowance: null is paired with allowance_error; onboarding: null with onboarding_error. Both mean unknown, never fine — do not tell an operator they have room, or that nothing is outstanding, on the strength of a null.
• fleet_logins reports two lanes and never sums them. lease is the build credential (lapsed → builds fall back to metered pricing); desk is what the box's terminal opens (lapsed → the desk will not start). A box can be perfect on one and unusable on the other, so a single total could not say which broke. Desk state is four-valued — healthy | not_applicable | unknown | lapsed — and "nobody asked OPVS to manage this desk" is a different sentence from "OPVS was asked and cannot vouch for it".

All tool names match ^[a-zA-Z0-9_-]+$ (the OpenAI tool-name regex; dots break Lola/Roni/planner on first call).

Install

This package is published to both public npm and OPVS's Verdaccio registry (npm.opvs.ai). A plain npm install -g @opvs-ai/mcp works from npmjs.com. Inside a repo whose .npmrc pins the @opvs-ai scope to Verdaccio, that pin wins over any --registry flag — including on reads, so verify with the scope override:

echo "@opvs-ai:registry=https://npm.opvs.ai/" >> ~/.npmrc
npm install -g @opvs-ai/mcp

Provides the opvs-mcp binary.

npm view @opvs-ai/mcp version --@opvs-ai:registry=https://registry.npmjs.org

Corrected 2026-08-18. This section used to say the npmjs publish was deferred and that the package was Verdaccio-only. That stopped being true when the 2.x line reached npmjs; the note outlived the condition it described. Read the registry, not this file.

Auth

Reads ~/.opvs/config.json (shared with @opvs-ai/cli). If you've already run opvs auth request, this MCP works immediately. The brand is pinned server-side from the PAT — tool_call will refuse if the PAT isn't brand-scoped.

npm install -g @opvs-ai/cli @opvs-ai/mcp
opvs auth request -w <workspace-slug> -e <admin-email>
# (approve the email link)
opvs whoami     # confirm brand pinned

MCP client config

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "opvs": {
      "command": "opvs-mcp",
      "env": { "NODE_NO_WARNINGS": "1" }
    }
  }
}

Restart Claude Desktop. tool_search, tool_help, tool_call, etc. appear in the tools menu.

Cursor

~/.cursor/mcp.json or via Settings → Cursor Settings → Features → MCP:

{
  "mcpServers": {
    "opvs": {
      "command": "opvs-mcp",
      "env": { "NODE_NO_WARNINGS": "1" }
    }
  }
}

Antigravity

Settings → MCP → Add server. NODE_NO_WARNINGS=1 is required — Antigravity rejects any stderr text before the JSON-RPC handshake (see antigravity-debrief memory for the 2026-04-26 incident).

{
  "mcpServers": {
    "opvs": {
      "command": "opvs-mcp",
      "env": { "NODE_NO_WARNINGS": "1" }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "opvs": {
      "command": "opvs-mcp",
      "env": { "NODE_NO_WARNINGS": "1" }
    }
  }
}

Claude Code

claude mcp add opvs -- opvs-mcp

Worked example

You: Find restaurants near Aarhus and save the top 5 to a board.

Agent → tool_search({ intent: "find restaurants in Aarhus" })
     ← { items: [{ vendor: "@spideriq", name: "lead-gen-skills", ... }],
         telemetry_signal: "warm",
         _guidance: "#audit.ok ranked=1 best=@spideriq/lead-gen-skills #next:tool_call" }

Agent → tool_help({ name: "@spideriq/lead-gen-skills", section: "methods" })
     ← { methods: { search_maps: { ... }, submit_job: { ... } } }

Agent → tool_call({
          skill: "@spideriq/lead-gen-skills",
          method: "submit_job",
          params: { type: "spiderMaps", payload: { query: "restaurants", location: "Aarhus" } }
        })
     ← { job_id: "...", _guidance: "#audit.ok #next:poll getJobStatus every 5s" }

The agent never had to know all of SpiderIQ's 40+ methods upfront — discovery → describe → invoke flowed through 3 always-on tools (discover → describe → invoke).

Response contract

Every tool returns a single text-content block whose payload is JSON with:

• Flat sibling _guidance: string — never a wrapper, never an array.
• Optional flat sibling _findings: [...] — only when the server emits one (e.g. audit_level=all).
• telemetry_signal in search results — closed enum: absent | cold | warm | hot.

The contract was locked with SpiderIQ on 2026-05-15 PM. See docs/planning/Marketplace/architecture/skills-system-reference.md for the gateway-side semantics this MCP mirrors.

tool_pin status

tool_pin is a stub in 1.0.0. The W2.1 TOOLS.md persistence layer is live in the gateway's skills-meta plugin (PUT /api/v1/agents/{id}/tools-md via Management API + X-API-Key), but that surface isn't reachable from a PAT-authenticated MCP client. Calling tool_pin returns:

{
  "action": "pin",
  "skill": "@opvs-ai/agentboard",
  "agent_id": "lola_001",
  "changed": false,
  "_guidance": "#audit.warn:not-supported-via-mcp — ..."
}

Until W2.MCP.PIN ships the PAT-gated passthrough, manage pins via the OPVS dashboard agent profile editor at /admin/agents/personas.

What was deprecated

This package was previously a 209-tool monolithic MCP exposing every public skill's full surface. That model didn't survive contact with MCP clients — every real client (Antigravity, Cursor, Claude Desktop, Windsurf) enforces a ~100-tool cap and the monolithic build was unusable in practice.

The on-demand model (10 always-on + tool_call indirection) reaches the same skills without paying the tool-budget cost.

Versions ≤ 0.7.4 are end-of-life. There is no @opvs-ai/mcp@0.x → 1.0 migration code path — replace the old install with a fresh one.

Development

cd ../core && npm install && npx tsc   # REQUIRED FIRST — see below
cd ../mcp  && npm install
npx vitest run                          # unit tests
npm run build && OPVS_TOKEN=smoke-test npm run list-tools

Two things bite from a clean checkout:

• Build @opvs-ai/core first. Its main points at dist/, so without that step the suite dies at collection with Failed to resolve entry for package "@opvs-ai/core" — a missing build, not a broken suite.
• npm run list-tools is a real gate, not a printout. It drives the actual stdio protocol against the built server and exits non-zero on a tool name that fails ^[a-zA-Z0-9_-]+$ (exit 2) or on going over the tool-count ceiling (exit 3). A unit test of the TOOLS array cannot prove a tool is registered; this can. Both run in CI under TS Library Tests.

Counts move. Measure them at your SHA rather than citing a number from here.

Related packages

• @opvs-ai/cli — terminal access (no MCP layer)
• @opvs-ai/skills — vendor CLI (publish/install/doctor)
• Gateway plugin skills-meta (source) — the in-platform counterpart of this package

License

MIT — see LICENSE.