Backplane MCP Server

An MCP server that exposes the Backplane platform to AI agents. The live catalog spans workspaces, boards, cards, executions, approvals, notes, resources, and pipeline configuration, plus role-specific prompts and resources. Use get_server_info or the in-app MCP reference for the catalog served by the version you are running instead of relying on a frozen tool count.

Point any MCP-capable client (Claude Code, Claude Desktop, or your own agent) at a Backplane instance and it can read board state, claim and move cards, log executions, and request approvals.

Install

uvx backplane-mcp

Or from source:

uvx --from "git+https://github.com/Valaris-Studio/backplane.git#subdirectory=mcp-server" backplane-mcp

Configure

Add to your MCP client's config (e.g. ~/.claude.json or claude_desktop_config.json):

{
  "mcpServers": {
    "valaris": {
      "command": "uvx",
      "args": ["backplane-mcp"],
      "env": {
        "VALARIS_API_URL": "https://your-backplane-host",
        "VALARIS_API_KEY": "vlr_..."
      }
    }
  }
}

Upgrading from 0.5.0

0.6.0 lists the interactive default hand instead of every tool. To keep the full surface an existing config had, add one line to the server env:

"VALARIS_MCP_TOOLSETS": "all"

Runner launches need nothing: a present VALARIS_MCP_ALLOWLIST with no toolsets env loads every toolset, and new runner binaries pin all.

For an autonomous runner, or whenever you want the full surface, add VALARIS_MCP_TOOLSETS:

{
  "mcpServers": {
    "valaris": {
      "command": "uvx",
      "args": ["backplane-mcp"],
      "env": {
        "VALARIS_API_URL": "https://your-backplane-host",
        "VALARIS_API_KEY": "vlr_...",
        "VALARIS_MCP_TOOLSETS": "all"
      }
    }
  }
}

The default hand covers project context, search, boards, cards, notes and the other knowledge tools, plus a few read-only helpers (linked git repos, the board's skills, velocity and cost), leaving workspace-admin and destructive verbs, the collaboration setup tools and the rest of the autonomous-operations tools opt-in. The env var picks the initial hand only. Every hand, including the default one, also carries the server-info category: get_server_info, whoami and enable_toolsets. Call get_server_info and read its toolsets key to see what is loaded and which toolset ids exist; call enable_toolsets(toolset_ids) with any of those ids (all, default, or a group/category id) to widen the running session without a restart. Widening is widen-only, idempotent and per-process, and after one that adds tools the server sends notifications/tools/list_changed (the handshake advertises tools.listChanged: true). A client that ignores that notification still needs VALARIS_MCP_TOOLSETS to see a wider hand. VALARIS_MCP_ALLOWLIST stays a ceiling the tool never lifts: resolved_tool_count in get_server_info is the size of the loaded toolsets before the allowlist intersection; enabled_tools is the hand after it.

The server name valaris is a stable, permanent namespace — agent tool names are mcp__valaris__*. It is intentionally not renamed alongside product branding, because renaming it would break every existing agent config. The valaris-mcp console script remains as an alias of backplane-mcp.

Upgrading

Upgrading from 0.7.0

0.7.1 changes nothing in existing configs. It adds enable_toolsets, so an interactive session widens its hand at runtime instead of restarting with a wider VALARIS_MCP_TOOLSETS; runner grants are unaffected.

Retired or renamed tools stay callable for one minor version as deprecated aliases: get_server_info lists them under deprecated_aliases with their replacement and deprecated_removed_in, and allowlist_deprecated names the ones a VALARIS_MCP_ALLOWLIST still grants. The CHANGELOG carries the rename → replacement table for each release.

Getting started as an agent

Start with get_project_context — one call returns the board definition, a board summary, notes, git repos, and recent activity. Then use the prompt matching your role (init_project, standup, plan_work, pickup, …).

Autonomous runners must claim work through next_assignment, never by searching and claiming manually: the backend scheduler applies every role-aware filter and atomically reserves one card with its bundled context. Interactive agents and humans claim by moving the card into the column resolved by column_type and adding themselves as a participant.

Development

pip install -e ".[dev]"
pytest
ruff check src/

A drift guard in the platform's backend test suite asserts this server's tool catalog stays in sync with the frontend's documentation catalog, so adding a tool requires updating both.

License

AGPL-3.0-or-later — see LICENSE. The MCP tool and prompt schemas (names, descriptions, input/output JSON Schemas) are additionally available under Apache-2.0 so integrations can implement against them freely; see LICENSES.md in the repository root.