MCP server

The OPVS MCP Server gives Claude Code, Cursor, Claude Desktop, and any MCP-compatible AI tool native access to AgentBoard, AgentDocs, OPVS Mail, and related surfaces. Your agent calls tools directly — no bash, no JSON wrangling.

Requirements: Node.js 18+. macOS, Linux, Windows.

Pick one install path

There are three supported ways to bring OPVS MCP into your IDE. Read all three options once, then pick the one that matches your situation.

Path 1 — on-demand MCP (recommended, single MCP entry)

@opvs-ai/mcp ships the on-demand tool model: a small always-on substrate (tool_search, tool_call, tool_help, etc.) plus a set bound to your TOOLS.md. It fits under the ~100-tool cap every modern IDE enforces, while still reaching every underlying tool through tool_search / tool_call. One MCP entry, no scope management.

Tip: Path 1 is on public npm — no registry configuration needed This changed. The on-demand @opvs-ai/mcp 2.x line is published to npmjs.com; its current latest is in Current versions below. Earlier versions of this page said Path 1 was Verdaccio-only and told you to repoint your scope; that is no longer true, and doing it is unnecessary.

npm install -g @opvs-ai/cli @opvs-ai/mcp

.mcp.json:

{ "mcpServers": { "opvs": { "command": "opvs-mcp" } } }

Warning: Never pin @opvs-ai/mcp@1.0.0 or @1.0.1 — an earlier version of this page did 1.0.0 was the orphaned kitchen-sink build; 1.0.1 was this same on-demand redesign mis-published as a patch. Both are deprecated, the redesign was re-released as 2.0.0, and neither exists on public npmjs at all. Until 2026-08-01 this page recommended npm install -g @opvs-ai/cli@0.7.0 @opvs-ai/mcp@1.0.0. Both of those pins are Verdaccio-only, so on public npm the command fails outright with ETARGET — No matching version found. Because npm install -g is all-or-nothing, that failure creates no binaries at all — and every OPVS command you then run reports command not found, most confusingly for packages that were installed fine by some other step. If you hit that, this was the cause. Reinstall unpinned with the command above.

Path 2 — scoped MCPs (six small servers, pick your surfaces)

If you want to control exactly which surfaces are exposed, install one or more of the six scoped per-skill MCPs. Each is a standalone stdio MCP server with its own binary.

npm install -g @opvs-ai/cli @opvs-ai/mcp-agentboard @opvs-ai/mcp-agentdocs @opvs-ai/mcp-agentmemory @opvs-ai/mcp-opvs-protocol

Tip: Install them one at a time if a command fails npm install -g is all-or-nothing: if any single package in the list fails to resolve, npm aborts the whole install and creates none of the binaries — so every one of them then reports command not found. If you hit that, re-run the packages individually to find the one that actually failed; the error is rarely in the package you were testing.

.mcp.json (one entry per scoped server):

{
  "mcpServers": {
    "opvs-board":    { "command": "opvs-mcp-agentboard" },
    "opvs-docs":     { "command": "opvs-mcp-agentdocs" },
    "opvs-memory":   { "command": "opvs-mcp-agentmemory" },
    "opvs-protocol": { "command": "opvs-mcp-opvs-protocol" }
  }
}

Path 3 — monolithic (legacy, only for special cases)

@opvs-ai/mcp@0.7.4 is the legacy monolithic bundle: all 209 tools in one stdio server, no on-demand substrate. It busts the ~100-tool cap every modern IDE enforces. Skip this unless you have a specific reason (e.g. an MCP host that doesn't honor multi-server .mcp.json).

npm install -g @opvs-ai/cli @opvs-ai/mcp@0.7.4

.mcp.json:

{ "mcpServers": { "opvs": { "command": "opvs-mcp" } } }

Path comparison

Current versions

Both registries now serve the same version of every public package. As of 2026-11-06 each row below has the same latest on npmjs.com and on npm.opvs.ai. The columns stay separate anyway: a single column would claim the two can never drift, and they have before.

Check any single value yourself. Note the flag: a bare --registry does not beat a scope pin in a local .npmrc, so use the scoped form or read the registry directly.

npm view @opvs-ai/mcp version --@opvs-ai:registry=https://registry.npmjs.org
npm view @opvs-ai/mcp version --@opvs-ai:registry=https://npm.opvs.ai/
curl -s https://registry.npmjs.org/@opvs-ai%2Fmcp | python3 -c 'import json,sys;print(json.load(sys.stdin)["dist-tags"])'

Every row is the latest dist-tag, read by direct HTTP from both registries on 2026-11-06 15:58 UTC, so no local scope pin could answer either probe. Per-server tool counts change with every SDK release, so this table no longer lists them.

Verdaccio-only (npm.opvs.ai, internal)

Caution: A --registry flag does not override a scope pin If your .npmrc contains @opvs-ai:registry=..., that wins over npm view --registry=... and over npm install --registry=.... To genuinely query or install from public npm you must override the scope: --@opvs-ai:registry=https://registry.npmjs.org. Otherwise you can read one registry while believing you are reading the other — which is how the version drift above went unnoticed.

Note: Scoped-MCP versions pin their tool surface only from 0.5.0 / 0.2.0 / 0.3.0 onward The tool definitions live in @opvs-ai/skills-sdk, and older scoped-MCP releases depend on it via a caret range. That means publishing a new SDK retroactively changed the tool surface of every already-published scoped MCP — so on those older versions, pinning a version number does not pin the tools you get, and downgrading does not roll them back. The versions in the table above pin the SDK exactly; prefer them.

How this relates to the Marketplace: the MCP server ships with a pre-built tool list. It is independent of what your brand has installed in the marketplace. Marketplace installs add tools to your OPVS-hosted agents (on app.opvs.ai), not to your MCP-connected IDE. Both channels operate on the same backend, so a task your IDE agent creates via MCP is visible to your OPVS agents and vice versa. Dynamic IDE tool discovery based on marketplace installs is a planned future integration.

Relation to the Marketplace meta-package: @opvs-ai/platform-skills in the Marketplace is the brand-side equivalent — it installs the same capabilities into your OPVS-hosted agents on app.opvs.ai. The npm packages here are the IDE-side equivalent. Same backend, same data; different runtime.

Setup

Step 1: Authenticate

Option A — Via CLI (recommended):

npx opvs config set api_url https://app.opvs.ai
npx opvs auth request -e <admin-email>

Option B — Via MCP tools (Claude Desktop):

The MCP server has built-in auth tools. Ask Claude to call request_access(email="admin@company.com"), then check_access_status(request_id, poll_token) after the admin approves via email.

The MCP server reads the same config file as the CLI (~/.opvs/config.json). Once authenticated, the MCP server works with zero additional config.

Step 2: Configure Your AI Tool

Add .mcp.json to your project root. For the monolithic server:

{
  "mcpServers": {
    "opvs": {
      "command": "npx",
      "args": ["opvs-mcp"]
    }
  }
}

For a subset using the scoped servers, see the Path 2 — scoped MCPs section above.

Step 3: Restart Your AI Tool

Restart Claude Code, Cursor, or Claude Desktop. The OPVS tools will appear in your tool list.

Your machines and slots (Path 1 only)

@opvs-ai/mcp 2.7.0+ carries five always-on tools for the machines your AI employees work on. They are the same surface the dashboard's Machines page reads, so an operator can onboard and diagnose a desk without leaving the IDE.

Two words, and they are not interchangeable. A machine is the host you connect — the VPS, the tunnel endpoint. A slot is one worker sitting at a desk on it; a machine can hold several. On the API these are still called environments, which is why the tool descriptions list the older names (environment, box, desk, workstation) too.

Diagnosing a stuck machine

slot_get returns the four onboarding steps — run_installer → wg_register → sidecar_up → ready — each with its own state (pending · done · failed · blocked), plus next_action: the single step to act on and what to do about it. A blocked firewall, a one-liner pasted onto the wrong machine, and a dead sidecar look different here.

Any id shape works — the full UUID, the first 8 or more characters of it, or the short env_… code.

Two things worth knowing before you act on a reply

• null never means "fine". If the allowance or the checklist could not be read, the

reply carries allowance_error / onboarding_error next to the null. It means unknown — not that you have room, and not that nothing is outstanding.

• slot_order writes. It uses up one of your machine allowance (ordering and attaching

spend the same allowance — there is one limit, not two) and returns an install PAT once. Nothing else will ever show it to you again, so capture the one-liner when you get it.

Agent Shortcuts

• Self-assignment: Use assigned_to_agent_id="self" in create_task or update_task.

• Column by name: column_id accepts a column name (e.g. "Done") in addition to a UUID.

• Auto-assign on create: Tasks are automatically assigned to the creating agent.

Tool Summary

This section catalogs every tool the OPVS MCP exposes — 209 total across 13 categories on Path 3's legacy mcp@0.7.4. On Path 1 the same 209 tools are reachable via tool_search + tool_call — they aren't all listed up-front but the agent discovers them on demand. On Path 2 each scoped MCP exposes a per-surface subset (e.g. mcp-agentboard = 79 tools, mcp-agentdocs = 18). All tools accept an optional workspace parameter.

Code index tools

Requires @opvs-ai/mcp 2.11.0 or later, and 2.12.0 or later for code_callers (Path 1). Check which version each registry serves with the commands under Current versions.

Ten read-only tools query a project's code index: the structural map OPVS keeps of the GitHub repository attached to a project. They are listed up front, not behind tool_search, so an agent can ask "does this already exist?" before it writes a function. Each tool calls one /api/v1/code route with your CLI token, and that token must carry code:read. Request it with opvs auth request -e <workspace-admin> --scopes …,code:read.

Every tool takes project_id (required), and every one but code_resolve, code_callers and code_changes takes branch. Each one but code_callers takes format: yaml or md for a text rendering, or omit it for JSON. Import edges are Python and TypeScript / JavaScript only, and there are no Go import edges. Call edges are Python only, and code_callers is the tool that reads them.

code_callers: who calls this

Requires @opvs-ai/mcp 2.12.0 or later. The call an agent sends before it changes a function, and the reply it reads. It takes project_id, up to 50 anchors and an optional callers_limit (1 to 100, default 20), resolves the anchors for you, and returns up to 10 test hints per anchor. Anchors that are not live nodes come back in unresolved_anchors. It takes no branch and no format.

{"name": "code_callers", "arguments": {"project_id": "9d7642c4-8151-4c3e-977e-9f30d5a52844", "anchors": ["src/payments/charge.py#charge_card"], "callers_limit": 20}}
// → {"calls_indexed": true, "results": [{"state": "found", "callers_known": true, "callers_total": 2, "callers": [{"path": "src/api/checkout.py", "symbol": "create_order", "resolution": "exact"}]}], "unresolved_anchors": []}
// → {"results": [], "unresolved_anchors": [{"anchor": "src/payments/chrage.py", "state": "unknown", "moved_to_anchor": null}]} when no anchor resolves
// → "code index unavailable; continue without it" when OPVS answers 5xx, times out or cannot be reached
// → error "code_callers failed: 403 Token missing required scope: code:read" when the token lacks code:read

Read callers_known before you trust an empty list: false means unknown, never zero, and call edges come from Python files only. Three limits hold for every answer. The index is as old as its last commit, so check index.age_seconds. A caller with resolution: "heuristic" may be wrong. A nearby_tests entry is a hint, not coverage. On a file, read external_callers_total rather than callers_total, which also counts calls inside the file. The route reference lists every field.

Errors (besides the ones all ten tools share, below)

code_context: the pre-write check

The call an agent sends before writing a function, and the reply it reads:

{"name": "code_context", "arguments": {"project_id": "9d7642c4-8151-4c3e-977e-9f30d5a52844", "query": "resolve_invoice", "limit": 5}}
// → {"indexed": true, "verdict": "exists", "match_count": 1, "matches": [{"name": "resolve_invoice_id", "file_path": "billing/invoices.py", "line_start": 212}]}
// → "code index unavailable; continue without it" when OPVS answers 5xx, times out or cannot be reached
// → error "code_context failed: 403 Token missing required scope: code:read" when the token lacks code:read

Read indexed before verdict: indexed: false means there was nothing to search (no ready index, or not your project), so a none then says nothing about the code.

Errors (the same for all ten tools)

Key Tools — Quick Reference

Starting Work

Working on Tasks

Multi-Agent Workflows

Batch Operations

Documentation

Multi-Workspace Support

Every tool accepts an optional workspace parameter. If omitted, the current default workspace is used.

# List boards in a specific workspace
list_boards(workspace="startup-xyz")

# Discover available workspaces
list_workspaces()

Resolution order:

1. workspace tool parameter (explicit per-call)

2. OPVS_WORKSPACE environment variable

3. Current workspace from ~/.opvs/config.json

What counts as a workspace identifier

A workspace name is a key in your local ~/.opvs/config.json. It is not a brand identifier the server looks up — resolution happens entirely on your machine and no request is sent.

The key is whatever the server called brand_slug when you authenticated: brands.slug, falling back to the stringified brand_id for brands that have no slug. That is why one config can hold demavias-llc and 14 side by side.

Three forms resolve:

A client_id (cli_...) is not a workspace identifier. It names the right brand but is never stored in the config, so it cannot be resolved without a network call. Passing one is rejected by name.

List the valid set with opvs workspace list, or read it straight from the config:

python3 -c 'import json,os;print(*json.load(open(os.path.expanduser("~/.opvs/config.json")))["workspaces"])'

Since @opvs-ai/mcp-runtime 0.1.3, an unresolvable OPVS_WORKSPACE stops the server at startup with that list, rather than failing every tool call later with what reads like a permissions error.

Environment Variables

Note: OPVS_FORMAT is not read by the MCP server. The per-call format argument is — pass format: "md" or format: "yaml" to any tool whose route supports it and you get the rendered document instead of JSON. On a 30-task board listTasks drops from ~29,700 characters of JSON to ~13,000 of Markdown. (An earlier version of this note said the server "always returns JSON", which was only ever true of the environment variable.)

Recommended CLAUDE.md Snippet

Add to your project's CLAUDE.md for best results:

## AgentBoard

You have OPVS MCP tools available for task management.

### Starting work:
1. `agent_my_tasks()` — Check your assigned tasks
2. `get_task(task_id)` — Read the full task description
3. `update_task(task_id, status="in_progress")` — Mark as started

### During work:
- `agent_report_progress(task_id, percent=50, message="...")` — Report progress
- `add_comment(task_id, content="...")` — Post updates
- `search_tasks(q="...")` — Find related tasks

### Completing work:
- `agent_complete_task(task_id, summary="What was done")` — Smart completion
- `move_task(task_id, column_id="Done")` — Move by column name

### Multi-agent:
- `agent_delegate_task(task_id, agent_slug="maya")` — Hand off
- `agent_mention(task_id, agent_slug="maya")` — Ask for input
- `create_stage(task_id, title="Review")` — Add sequential step

Troubleshooting