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.
Connect an agent
Section titled “Connect an agent”Claude Code:
claude mcp add plune -- npx -y @plune-ai/cli@0.39.9 mcp serveCodex, 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.
| Flag | What it does |
|---|---|
--project <id> | The project the tools work in. Default: PLUNE_PROJECT, else the token’s own project. |
--read-only | Offer only the read tools, as for a read token. |
A project file the whole team shares
Section titled “A project file the whole team shares”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"].
The tools
Section titled “The tools”These 17 tools are listed from the start:
| Tool | What the agent does with it |
|---|---|
plune_project_context | Start here: the project’s suite tree, how many cases it has, its missions and how much waits in the review queue. |
plune_get | Read one test case, run or review queue entry in full by its id. |
plune_cases_search | Find cases by suite, state, tag, priority or text, a page at a time. |
plune_review_list | List what waits for review. |
plune_review_decide | Approve or reject up to 100 entries. The first call is a preview; the same call with its confirm value applies it. |
plune_case_propose | Propose up to 100 new cases. They land in the review queue. |
plune_cases_generate | Ask 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_get | Read 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_update | Start, read and move a mission. |
plune_source_add | Add a source to a mission. |
plune_question_ask, plune_question_list | Ask a person a question, and read the answers. |
plune_strategy_propose | Propose a mission’s strategy. |
plune_report_request | Ask for a mission’s completion report. It needs an accepted strategy. |
plune_discover_tools | Show 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 rules an agent works under
Section titled “The rules an agent works under”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.
Protocol revisions
Section titled “Protocol revisions”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 client | What it gets |
|---|---|
Opens with initialize: revision 2025-11-25 and older | plune_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-28 | supportedVersions: ["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
$schemavalue. - Calling a tool that is not in the list is a protocol error,
-32602, rather than a tool result withisError. That includes a hidden tool called beforeplune_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.
Keep the tool list small
Section titled “Keep the tool list small”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_toolstakesnames, so the agent can switch on one. A2026-07-28client 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.limitsets 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.
What the tests hold the tools to
Section titled “What the tests hold the tools to”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 narrowedenum, 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 list | Tools | Estimated tokens | Test limit | Counted by a provider |
|---|---|---|---|---|
| Write token, as listed first (both lines) | 17 | 8,853 | 9,272 | 8,922 |
Write token, after plune_discover_tools (2025 line) | 22 | 11,329 | 11,926 | 10,847 |
Read token, or --read-only | 8 | 2,716 | 2,731 | 1,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.
readOnlyHintanddestructiveHinttell a client what the server says about a tool; the lint even flags one today (plune_mission_updaterewrites a mission’s brief and can remove its address, but saysdestructiveHint: 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):
npx -y @plune-ai/cli@0.39.9 mcp lint -- npx -y @plune-ai/cli@0.39.9 mcp serveWith 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.