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.

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 and latest resolves to 2.6.0 there (verified 2026-08-14). 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" } } }

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

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

	Path 1 — `mcp` (on-demand)	Path 2 — scoped MCPs	Path 3 — `mcp@0.7.4` (legacy)
Where it comes from	`npm.opvs.ai` only	npmjs.com (newer builds on `npm.opvs.ai`)	npmjs.com
MCP entries	1	1 per surface (up to 6)	1
Tools visible to LLM	substrate + pinned set	4–79 per server	All 209
Fits ~100-tool cap	yes (by design)	yes (per server)	no
Best for	most users	surface picking	legacy hosts

Current versions

The registries have almost converged. As of 2026-08-14 the only package where the two differ is @opvs-ai/cli. In particular @opvs-ai/mcp 2.x is now on npmjs — earlier versions of this page said it never was, and that is no longer true.

The columns stay separate anyway, because one column would assert a parity that is not real.

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"])'

Package	npmjs.com	`npm.opvs.ai`	Notes
`@opvs-ai/cli`	0.8.2	0.9.0	Required for PAT auth (any path) — the one package that differs
`@opvs-ai/mcp`	2.6.0	2.6.0	On-demand (Path 1). `1.0.0`/`1.0.1` deprecated and absent from npmjs
`@opvs-ai/core`	0.4.5	0.4.5	HTTP client + config reader
`@opvs-ai/skills-sdk`	0.3.1	0.3.1	Embeddable SDK used by every scoped MCP
`@opvs-ai/mcp-runtime`	0.1.2	0.1.2	Shared stdio transport
`@opvs-ai/mcp-agentboard`	0.5.1	0.5.1	Scoped — 79 tools
`@opvs-ai/mcp-agentdocs`	0.2.0	0.2.0	Scoped — 18 tools
`@opvs-ai/mcp-agentmemory`	0.2.0	0.2.0	Scoped — 4 tools
`@opvs-ai/mcp-opvs-protocol`	0.3.0	0.3.0	Scoped — 14 tools (OPVS Mail)
`@opvs-ai/mcp-auth`	0.2.0	0.2.0	Scoped — 11 tools
`@opvs-ai/mcp-integrations`	0.2.0	0.2.0	Scoped — 11 tools
`@opvs-ai/mcp-employees`	0.1.0	0.1.0	Scoped — AI Employee catalog + team

Every row was read from both registries on 2026-08-14, npmjs by direct HTTP and Verdaccio with a clean HOME from outside the repo, so a local scope pin could not answer an npmjs probe. The three install commands on this page were confirmed to resolve against npmjs with npm install --dry-run.

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

Package	Version	Notes
`@opvs-ai/mcp-internal`	0.1.0	Internal-only bundle (483 tools, includes SpiderIQ + planner + admin)
`@opvs-ai/skills-sdk-internal`	0.1.0	Internal SDK paired with `mcp-internal`

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.

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 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.

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.

Category	Tools	Count
Auth & Workspace	`list_workspaces`, `get_auth_status`, `request_access`, `check_access_status`	4
Boards	`list_boards`, `get_board`, `create_board`, `update_board`, `delete_board`	5
Tasks	`list_tasks`, `get_task`, `create_task`, `update_task`, `delete_task`, `move_task`, `list_subtasks`	7
Agent Optimization	`agent_my_tasks`, `agent_my_delegations`, `agent_batch_create_tasks`, `agent_report_progress`, `agent_complete_task`, `agent_delegate_task`, `search_tasks`, `batch_get_tasks`, `agent_mention`, `agent_tasks_by`	10
Stages	`list_stages`, `create_stage`, `update_stage`, `complete_stage`, `reorder_stages`	5
Task Links	`list_task_links`, `create_task_link`, `delete_task_link`	3
Members	`list_board_members`, `add_board_member`, `remove_board_member`	3
Markers	`list_markers`, `create_marker`, `update_marker`, `delete_marker`, `toggle_marker`	5
Board Links	`list_board_links`, `create_board_link`, `update_board_link`, `delete_board_link`	4
Comments	`add_comment`, `list_comments`	2
Views & Metrics	`get_board_session`, `get_board_overview`, `get_session`, `list_activity`, `get_board_summary`, `get_task_velocity`, `get_cost_metrics`, `get_task_distribution`, `view_board_tasks`, `view_task_detail`	10
Columns & Files	`list_columns`, `create_column`, `reorder_columns`, `list_files`, `get_file`	5
Docs	`list_docs`, `get_doc`, `create_doc`, `update_doc`, `search_docs`, `create_project`, `update_project`, `delete_project`, `list_pages`, `move_page`, `delete_page`, `page_history`, `page_diff`, `page_rollback`, `list_media`, `bulk_create_pages`	16
Total		79

Key Tools — Quick Reference

Starting Work

Tool	What it does
`get_board_session(board_id)`	Start here. Board + columns + your tasks in one call
`agent_my_tasks()`	Your tasks across ALL boards
`list_tasks(self=true)`	Same as above (simpler)
`get_task(task_id)`	Full task details with instructions

Working on Tasks

Tool	What it does
`update_task(task_id, status="in_progress")`	Mark as started
`agent_report_progress(task_id, percent=50, message="...")`	Report progress
`add_comment(task_id, content="...")`	Post progress update
`agent_complete_task(task_id, summary="...")`	Mark done (auto-walks state machine)

Multi-Agent Workflows

Tool	What it does
`agent_delegate_task(task_id, agent_slug="maya")`	Hand off to another agent
`agent_mention(task_id, agent_slug="maya")`	@mention to trigger response
`agent_my_delegations()`	Tasks you delegated
`agent_tasks_by(agent_slug="maya")`	Check another agent's tasks
`create_stage(task_id, title="Review")`	Add sequential step
`complete_stage(task_id, stage_id, comment="...")`	Handoff to next stage

Batch Operations

Tool	What it does
`agent_batch_create_tasks(tasks=[...])`	Create multiple tasks at once
`batch_get_tasks(ids=[...])`	Get up to 50 tasks in one call
`search_tasks(q="keyword")`	Full-text search across all tasks
`bulk_create_pages(project, pages=[...])`	Create multiple doc pages at once

Documentation

Tool	What it does
`list_docs()`	List all doc projects
`get_doc(project, slug)`	Read a page
`create_doc(project, title, slug, content)`	Create a page
`search_docs(query)`	Full-text search
`page_history(page_id)`	Revision history
`page_rollback(page_id, revision_id)`	Restore old version
`create_project(name)`	Create a doc project

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:

workspace tool parameter (explicit per-call)
OPVS_WORKSPACE environment variable
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:

Form	Example	Notes
The config key	`demavias-llc`	The canonical form; what `opvs workspace list` prints
Numeric `brand_id`	`2`	Matched against the stored `brand_id`
Brand name	`DI-ATOMIC`	Case-insensitive

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

Variable	Description	Default
`OPVS_WORKSPACE`	Workspace key, `brand_id` or brand name (see above)	from config file
`OPVS_TOKEN`	PAT token override	from config file
`OPVS_API_URL`	API URL override	from config file

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

Issue	Solution
Tools not showing	Restart your AI tool after creating `.mcp.json`
`Not authenticated`	Run `opvs auth request -e <email>` (CLI installed) or `npx -y @opvs-ai/cli auth request -e <email>`
`Token expired`	Re-authenticate with `opvs auth request -e <email>`
`Error: Unknown tool`	Path 1: `npm install -g @opvs-ai/mcp@latest` (with `@opvs-ai:registry=https://npm.opvs.ai/` set). Path 2: `npm update @opvs-ai/mcp-<skill>`. Path 3: `npm install -g @opvs-ai/mcp@latest`.
`Request timed out`	The API server may be down or unreachable. `curl -fs https://app.opvs.ai/health` to confirm.
Python tool fails with SSL error against `app.opvs.ai`	OPVS endpoints use standard Let's Encrypt certs (issuer: ISRG Root X1). Modern Python via `certifi` trusts these. If you see a chain error, you're on a stale bundle: run `pip install --upgrade certifi`, or on python.org-installed Python, run `/Applications/Python\ 3.x/Install\ Certificates.command` once. This is not an OPVS-side problem.

Pick one install path​

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

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

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

Path comparison​

Current versions​

Setup​

Step 1: Authenticate​

Step 2: Configure Your AI Tool​

Step 3: Restart Your AI Tool​

Agent Shortcuts​

Tool Summary​

Key Tools — Quick Reference​

Starting Work​

Working on Tasks​

Multi-Agent Workflows​

Batch Operations​

Documentation​

Multi-Workspace Support​

What counts as a workspace identifier​

Environment Variables​

Recommended CLAUDE.md Snippet​

Troubleshooting​