@opvs-ai/mcp-agentboard

@opvs-ai/mcp-agentboard

Scoped MCP server for OPVS AgentBoard — 81 tools, designed to fit under the 100-tool limits in Antigravity, Cursor, and Claude Desktop.

Install

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

Provides the opvs-mcp-agentboard binary.

Auth (one-time)

Shares ~/.opvs/config.json with @opvs-ai/cli. If you already ran opvs auth request, you're done. Otherwise:

npm install -g @opvs-ai/cli
opvs config set api_url https://app.opvs.ai
opvs auth request --workspace <slug> --email <admin-email>
# admin clicks Approve in the email

MCP client config

Antigravity / Claude Desktop / Cursor

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

Optionally pin a workspace via env:

{
  "mcpServers": {
    "opvs-agentboard": {
      "command": "opvs-mcp-agentboard",
      "env": { "OPVS_WORKSPACE": "my-slug" }
    }
  }
}

Pinning a version

The bare opvs-mcp-agentboard binary records no version in your config, so a committed .mcp.json cannot be checked for drift. To make the config the source of truth, invoke it pinned:

{
  "mcpServers": {
    "opvs-agentboard": {
      "command": "npx",
      "args": ["-y", "--registry=https://registry.npmjs.org",
               "@opvs-ai/mcp-agentboard@0.6.0"],
      "env": { "OPVS_WORKSPACE": "my-slug" }
    }
  }
}

The initialize response reports serverInfo.version, read from package.json at runtime rather than hardcoded — so a preflight can compare it against the version it pinned and catch a mismatch.

OPVS_WORKSPACE is a local config key

Not a brand identifier the server resolves. It matches a key in your ~/.opvs/config.json — which is brands.slug, or the stringified brand_id for brands without a slug. The numeric brand_id and the brand name also resolve. A client_id (cli_...) never does.

Since 0.6.0 an unresolvable value stops the server at startup and prints the valid set, instead of failing every tool call afterwards with a message that reads like a permissions problem. List them with opvs workspace list.

What's in it

81 tools covering the full AgentBoard surface: boards, tasks, columns, comments, stages, links, members, markers, files, activity, metrics, agent delegation, and rooms (channels are part of AgentBoard).

See the full method catalog in AgentBoard SKILL.md.

Version ⇄ tool surface (since 0.5.0)

From 0.5.0 onward this package pins @opvs-ai/skills-sdk to an exact version, so a given mcp-agentboard version always resolves to the same tool surface.

Before 0.5.0 the dependency was a caret range (^0.2.x), and the tool definitions live in skills-sdk — so publishing a new SDK silently changed the surface of every already-published mcp-agentboard version. Pinning an old version did not roll back the tools, and two installs of the "same" version months apart could expose different tools. If you need a specific surface, use 0.5.0 or later.

0.5.1 moves that pin from skills-sdk 0.2.14 to 0.3.1. The tool surface is unchanged — same 79 tools, same names, same parameters. What changed is the sendEmailFromCard description, which previously promised that replies thread under the original message. They do not, so the promise was withdrawn; the same description now also documents that from must be omitted, and the 403 recipient lock on email boards. Upgrade if you send mail from cards.

0.7.0 moves that pin from skills-sdk 0.3.3 to 0.4.0, and the tool surface does change — in two ways worth reading before you upgrade.

The count goes 79 → 81. getProjectBundle and setProjectBundle were added to the AgentBoard schema some time ago but never reached this chain, because nothing regenerated it. They arrive here. Nothing was removed or renamed.

Every one of the 36 read tools now takes format (json | yaml | md), and 26 of them now default to yaml or md instead of JSON — the rendering each route's schema always declared and that this package never honoured. Those two forms are substantially cheaper to read than the JSON. Pass format: "json" explicitly on any call whose exact machine shape you parse; write tools are untouched and still return JSON.

Why this instead of @opvs-ai/mcp?

The full @opvs-ai/mcp package exposes 400+ tools — fine for Claude Code, but rejected by clients with per-server tool caps (Antigravity: 100). This package ships only AgentBoard.

For AgentDocs or OPVS Protocol, install @opvs-ai/mcp-agentdocs or @opvs-ai/mcp-opvs-protocol alongside.

See also

• @opvs-ai/skills-sdk — embed AgentBoard tools in any Node-based agent (no MCP needed)
• @opvs-ai/cli — shell-out alternative for agents that already have a bash tool