@opvs-ai/mcp

@opvs-ai/mcp

OPVS MCP server for the on-demand model — 10 always-on tools that give any MCP host (Claude Desktop, Cursor, Antigravity, Windsurf, Claude Code) the same surface OPVS-hosted agents see. 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)

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.

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.