Skip to content

Plune tools for AI agents (MCP)

plune mcp serve (from @plune-ai/cli 0.34.0) runs a Model Context Protocol server over stdio. An agent that speaks MCP — Claude Code, Codex, an IDE assistant — gets the Plune your token reaches as tools: it can read the project, search cases, work through the review queue, and run a mission from its sources to its report.

This page is about the Plune server. To test any MCP server — your own included — with plune mcp check, lint, snapshot and diff, see Test an MCP server, Lint an MCP server, Snapshot and diff and, for pull requests, MCP server checks in CI.

Claude Code:

Terminal window
claude mcp add plune -- npx -y @plune-ai/cli@0.39.9 mcp serve

Codex, in ~/.codex/config.toml:

[mcp_servers.plune]
command = "npx"
args = ["-y", "@plune-ai/cli@0.39.9", "mcp", "serve"]

Any other MCP client takes the same command: npx -y @plune-ai/cli@0.39.9 mcp serve.

The version is pinned on purpose. npx -y @plune-ai/cli with no version runs whatever is newest on the day, with no prompt, and plune mcp scan reports a launcher that starts an unpinned package (scan/cfg/unpinned-package). With the version pinned, scanning the .mcp.json below reports one info finding, scan/cfg/auto-confirm («installs without asking; the package is pinned»), which is the -y flag alone. Move the pin when you have read what changed in a new release.

The server reads the token the way every platform command does: PLUNE_TOKEN from the environment first, else the login plune login saved. Put PLUNE_TOKEN in the client’s env block rather than in the command line. Without a token the server does not start and exits 2.

FlagWhat it does
--project <id>The project the tools work in. Default: PLUNE_PROJECT, else the token’s own project.
--read-onlyOffer only the read tools, as for a read token.

A configuration file in the repository gives everyone who opens the project the same server. Both files below are committed, so neither holds the token: each reads PLUNE_TOKEN from the environment of whoever starts the client.

Claude Code, .mcp.json at the project root (format and ${VAR} expansion):

{
"mcpServers": {
"plune": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@plune-ai/cli@0.39.9", "mcp", "serve"],
"env": {
"PLUNE_TOKEN": "${PLUNE_TOKEN}"
}
}
}
}

In an interactive session Claude Code asks each person to approve a server from the project’s .mcp.json before it uses it.

Cursor, .cursor/mcp.json in the project, or ~/.cursor/mcp.json for every project (format and ${env:NAME} variables):

{
"mcpServers": {
"plune": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@plune-ai/cli@0.39.9", "mcp", "serve"],
"env": {
"PLUNE_TOKEN": "${env:PLUNE_TOKEN}"
}
}
}
}

In either file the flags go at the end of args, for example ["-y", "@plune-ai/cli@0.39.9", "mcp", "serve", "--read-only"].

These 17 tools are listed from the start:

ToolWhat the agent does with it
plune_project_contextStart here: the project’s suite tree, how many cases it has, its missions and how much waits in the review queue.
plune_getRead one test case, run or review queue entry in full by its id.
plune_cases_searchFind cases by suite, state, tag, priority or text, a page at a time.
plune_review_listList what waits for review.
plune_review_decideApprove or reject up to 100 entries. The first call is a preview; the same call with its confirm value applies it.
plune_case_proposePropose up to 100 new cases. They land in the review queue.
plune_cases_generateAsk the project’s AI for case proposals from pasted text (20 words to 12,000 characters, up to 12 proposals, 8 by default). It spends the project’s AI budget; the proposals land in the review queue. A Jira ticket by its key is not taken here: paste its text. From CLI 0.34.2.
plune_cases_generation_getRead where such a run stands: queued, running, done, failed or cancelled, with what it produced and what it cost. From CLI 0.34.2.
plune_mission_create, plune_mission_get, plune_mission_updateStart, read and move a mission.
plune_source_addAdd a source to a mission.
plune_question_ask, plune_question_listAsk a person a question, and read the answers.
plune_strategy_proposePropose a mission’s strategy.
plune_report_requestAsk for a mission’s completion report. It needs an accepted strategy.
plune_discover_toolsShow the tools below.

plune_discover_tools adds five more: plune_cases_update, plune_run_create, plune_results_write, plune_endpoint_propose, and plune_api_request — a raw request to any /v1/ route, for what no tool covers.

The server marks every request as an agent’s, so the platform holds the agent to the same rules as any agent session:

  • Nothing is created silently. A proposed case is a proposal in the review queue; a person approves it.
  • A batch stops at 100 items, and a bulk decision on the queue is previewed first and needs a confirm.
  • A delete is previewed first and needs a confirm, and the platform still refuses the deletes it refuses any agent session.
  • Every write tool takes dry_run: the agent sees the request it would send, and nothing is sent.

The same tools, without the MCP transport, are exported as @plune-ai/cli/mcp-tools for a service that gives its own agent the Plune tools.

From CLI 0.34.5 the server speaks both lines of the MCP protocol behind the same command. The client’s first message picks the line, so nothing needs configuring.

The clientWhat it gets
Opens with initialize: revision 2025-11-25 and olderplune_discover_tools switches the hidden tools on: the list grows, up to 22 tools, and the server sends notifications/tools/list_changed.
Opens with server/discover: revision 2026-07-28supportedVersions: ["2026-07-28"]. The list stays the same 17 tools for the whole connection, as that revision requires. plune_discover_tools describes the hidden tools with their input schemas and switches nothing on; the agent calls a hidden tool by its name.

A client that knows only 2026-07-28 works without the handshake, and a client that knows only the 2025 line works as before. Two things a 2025-line client sees differently from 0.34.5 on:

  • Tool schemas declare JSON Schema 2020-12 instead of draft-07. Every keyword they use exists in draft-07 too, but a client that validates schemas with a draft-07-only validator may refuse the new $schema value.
  • Calling a tool that is not in the list is a protocol error, -32602, rather than a tool result with isError. That includes a hidden tool called before plune_discover_tools. A client may pass a protocol error on to the model or not, so the agent may never read the hint to discover the tool first.

A client that hands the whole list to the model sends it with every request, so the list costs context whether the agent uses a tool or not. The numbers are in the next section.

  • Give the agent only what it needs. --read-only, or a read token, cuts the list from 17 tools to 8, under a third of the size.
  • Reveal only the hidden tools the task needs. With a 2025-line client, all five hidden tools add about 28% to every request after they are switched on. plune_discover_tools takes names, so the agent can switch on one. A 2026-07-28 client pays nothing for them: its list does not grow.
  • Ask for smaller pages. The most expensive answer is a page of plune_cases_search: 48 cases of our demo project (in Ukrainian) cost about 7,700 estimated tokens. limit sets the page size.

What a client does with the list is up to the client. Claude Code defers MCP tool definitions by default on current models (tool search): only the names load at the start, and a tool’s definition loads when Claude needs it. Cursor’s documentation describes switching a whole server on or off, not choosing single tools (Cursor MCP), so there --read-only is the way to a shorter list. We have not checked other clients.

The tool contract (names, descriptions, input and output schemas, annotations) is what an agent sees, and the platform’s built-in agent uses the same contract. Three tests in the CLI repository check every list a client can be shown: both protocol lines, a write and a read token, before and after plune_discover_tools. They run in CI on every pull request.

  • Snapshot. The repository holds every tool as the server lists it, in contracts/plune-mcp-tools.snapshot.json. Any difference fails the test: a renamed or removed tool, a new required parameter, a narrowed enum, a changed description. The file changes only when someone rewrites it on purpose, so the change shows in the pull request’s diff, and CI writes each change, classed breaking, non-breaking or informational, into the run summary.
  • Lint. The lists pass the rules of plune mcp lint. A deterministic error or warning fails the test, and no finding is excepted. Heuristic findings are advice and do not fail it.
  • Budget. The size of each list is measured and held to a fixed limit: 10% above the size measured when the limit was last set, in the work for CLI 0.37.0. A list that grows past its limit fails, and so does one that shrinks below 80% of it, so a limit cannot stay loose.

Measured with CLI 0.39.0 on 14 November 2026. The last column was counted with CLI 0.34.5 on 10 November 2026:

The listToolsEstimated tokensTest limitCounted by a provider
Write token, as listed first (both lines)178,8539,2728,922
Write token, after plune_discover_tools (2025 line)2211,32911,92610,847
Read token, or --read-only82,7162,7311,864

The estimate is the characters of each tool’s JSON as listed, divided by four: no tokenizer and no network, so the test gives the same number on every run. The last column is one model provider’s token-counting endpoint, for the name, description and input schema of each tool (what that API takes), without the provider’s own tool preamble of about 320 tokens. Other providers count differently, and we have not measured them. The biggest tool is plune_strategy_propose, 2,194 estimated tokens.

What these tests do not tell you:

  • They check the shape of the contract, not the agent’s choices. Nothing here shows that a model picks the right tool or fills its arguments well.
  • The annotations are the server’s own statements. readOnlyHint and destructiveHint tell a client what the server says about a tool; the lint even flags one today (plune_mission_update rewrites a mission’s brief and can remove its address, but says destructiveHint: false). What an agent can change is decided by the token’s scope and the platform’s rules, described above.
  • This page is not checked against the contract. A renamed tool fails the CLI’s tests; the table on this page follows by hand, at each CLI release.

You can run the same lint rules against the published server. With PLUNE_TOKEN in the environment (listing the tools does not call the platform):

Terminal window
npx -y @plune-ai/cli@0.39.9 mcp lint -- npx -y @plune-ai/cli@0.39.9 mcp serve

With CLI 0.34.5 it lists 17 tools and ends 0 errors, 3 warnings, 48 info, and exits 0. With --read-only after mcp serve it lists 8 tools: 0 errors, 0 warnings, 19 info.