MCP tools

Minga speaks MCP in three places:

Your tools: the external server at https://app.minga.run/mcp, for your own Claude Code or Codex session. It acts as you.
Agent tools: what Lea, other agents, workers and validators use inside their turns and runs. You don’t call these yourself.
The runner’s tool: open_pull_request, served on your machine to workers.

Every tool answers with the same JSON shape (below).

Your tools

Connect with Connect Claude Code and Codex over MCP. Every call:

acts as you, with your role in the project, under the same rules as the app;
reaches only projects in workspaces you are a member of, checked on every call (a project you can’t see answers exactly like one that doesn’t exist);
takes project as the project’s slug, name or id, or the git remote of a repo attached to it (github.com/acme/dictly, git@github.com:acme/dictly.git).

Tool	Read-only	What it does
`list_projects`	Yes	Your workspaces and projects: id, slug, name, repos (git remotes), link, how many decisions wait on you, and the lead. Call it first to find the project of this repo.
`read_project`	Yes	A project’s plan as compact JSON: goals, KPIs, areas, agents, items with refs, status and readiness, links between items, live runs, open cards and recent decisions; the brief and its version; plus the project’s link, what waits on you and your @handle.
`read_item`	Yes	One item in full: type, status, parents and children, owner and assignee, why it is or isn’t ready, the description, checks, blocker, review, runs with their results, outputs, links, the last 20 thread entries and related cards.
`plan`	No	Change the plan as you. Your changes need no approval.
`capture`	No	Capture an idea, feature, bug or question into the project’s triage. Lea sorts it.
`close_item`	No	Mark an item done or cancel it.
`comment`	No	Comment on a goal, item or other record; or post an update with a health; or record a decision.
`record_kpi`	No	Record one KPI number.
`needs_me`	Yes	What waits on you, across your projects or in one.
`answer`	No	Answer a plain question from `needs_me`.
`ask_lead`	No	Message the project’s lead in its chat and wait for the reply.

list_projects

No arguments. Returns, per workspace, its projects with id, slug, name, status, repos, url, needsMe and lead (name, handle). Live numbers are read for up to 20 projects, two seconds each; a project that does not answer in time shows needsMe: null.

read_project

Argument	Type	Notes
`project`	string	Required
`include`	array of `done`, `cancelled`, `archived`	Adds closed or archived items

Returns project.brief and project.briefVersion (12 hex characters), url, needsMe and you (your @handle), next to the plan. The plan part is capped at 48 KB.

read_item

Argument	Type	Notes
`project`	string	Required
`item`	string	A ref (`DIC-12`) or an id

plan

Argument	Type	Notes
`project`	string	Required
`rationale`	string, ≤ 2,000 characters	Why, in one or two sentences; a card shows it as the Why
`changes`	array of 1 to 300 changes	Graph commands as JSON (below)

Each change is a graph command: CreateGoal, CreateItem, UpdateItem, MoveItem, AssignItem, CloseItem, ReviseChecks, AddEdge, ReviseBrief and others; the tool’s input schema lists them all. In id positions you can use real ids, short refs (G-1, DIC-12), @handles, or $labels you define in the same call:

{
  "project": "dictly",
  "rationale": "Split the welcome screen work",
  "changes": [
    { "_tag": "CreateItem", "itemId": "$copy", "parentId": "DIC-130", "type": "task",
      "title": "Welcome screen copy", "why": "the first screen needs final text",
      "owner": "@lea", "assignee": "worker",
      "checks": [{ "_tag": "human", "approverId": null, "prompt": "Approve the copy" }] },
    { "_tag": "AddEdge", "kind": "blocks",
      "from": { "_tag": "item", "id": "$copy" }, "to": { "_tag": "item", "id": "DIC-133" } }
  ]
}

For a person, the tool also accepts:

History on CreateItem: status: "done" or "cancelled", with an optional one-line statusNote (≤ 500 characters). The item is owned by you and closed at once, and nobody is woken. status: "in_progress" on a leaf you do yourself (it is assigned to you).
ReviseBrief: body is the whole new brief; baseHash is project.briefVersion from read_project, or left out to write against the brief as it is now. It applies at once if you manage the project. An unchanged brief is refused, and one refused change refuses the whole call.

The answer returns the minted ids and refs for your $labels, and warns when items you created or moved are ready and a worker starts them now.

capture

Argument	Type	Notes
`project`	string	Required
`kind`	`idea`, `feature`, `bug`, `question`	Required
`title`	string, 1 to 200 characters	Required
`body`	string, ≤ 40,000 characters	Context, steps to reproduce
`area`	string	An area’s key or id

Text you capture is treated as outside input.

close_item

Argument	Type	Notes
`project`	string	Required
`item`	string	Required
`as`	`done`, `cancelled`	Required
`note`	string, ≤ 4,000 characters	Required: what happened
`evidence`	array, ≤ 20	For `done` on an item with command or output checks: `{run: "R-9"}`, `{artifact: "<id>"}`, or one check result per command check
`duplicateOf`	string	For `cancelled`: the item this duplicates
`supersededBy`	string	For `cancelled`: the item that replaces it

A done item still passes its later review stages.

comment

Argument	Type	Notes
`project`	string	Required
`target`	string	A goal, item or other record, by ref or id
`body`	string, ≤ 40,000 characters	Required
`health`	`on_track`, `at_risk`, `off_track`	Makes it an update: the record’s health until the next update
`decision`	boolean	Records a decision on the item or goal it shaped: what, why and the source. Not together with `health`.

An @mention of an agent in the body wakes it.

record_kpi

Argument	Type	Notes
`project`	string	Required
`kpi`	string	`K-3` or the KPI’s id
`value`	number	Required
`at`	epoch milliseconds	Any time inside the period the value describes; rounded down to the start of the KPI’s hour, UTC day or ISO week
`provisional`	boolean	The source is still settling
`n`	integer or null	The sample size, when it matters
`evidence`	array, 1 to 20	Optional for a person: a query, a tool call, a URL, a note, a run or an output

A newer sample for the same period replaces the older one; the history keeps both.

needs_me

Argument	Type	Notes
`project`	string	Optional: one project instead of all

Returns up to 50 entries: the project, the card’s ref, kind, one line, the prompt and options, the revision, whether you can answer it here (answerable), and a url to decide it in the app.

answer

Argument	Type	Notes
`project`	string	Required
`proposal`	string	The card’s ref (`P-7`)
`revision`	integer	From `needs_me`
`option`	string	An option key whose `answerable` is true
`text`	string, ≤ 8,000 characters	Free text, when the card allows it

Only plain questions can be answered here: you are the person the card is for, it holds up no item, and the option changes nothing in the plan. Everything else (plan approvals, review picks, permission prompts, outward actions, questions that hold work) answers Forbidden with “Approvals stay in the Minga app” and the link.

ask_lead

Exactly one of:

Argument	Type	Notes
`project` + `message`	string, 1 to 8,000 characters	A new message to the lead
`project` + `replyTo`	string	The `messageId` of an earlier call that answered `working`

The message appears in the lead’s chat with your name and “via Claude Code” (or Codex). The call waits up to 40 seconds. If the lead answered, it returns status: "answered" and the reply (cut at 8,000 characters); if not, status: "working" and a messageId to ask again later with replyTo. A project without a lead answers that it has none.

The import prompt

Prompt	Argument	What it does
`import_repo_state`	`project` (id, slug or name; the id is unambiguous), required	Reads the repo and puts its current state (brief, goals, KPIs, shipped and planned releases, open questions, past decisions) into the project, after you approve the draft. It never starts work.

In Claude Code: /minga:import_repo_state <project id> (the app shows it with the id filled in). Codex does not offer MCP prompts; the full text is in Import a repo’s state.

The server also sends short instructions to the client: what Minga is, which tool does what, and that approvals of plans and outward actions stay in the app.

Agent tools

Lea, role agents, workers and validators use these in their turns and runs. Each agent gets the tools its role needs, and every call is checked by the same rules as a person’s change, plus the agent’s autonomy level. They are listed here so you can read a transcript.

Read

Tool	What it does
`read_context`	The run’s context: the goal, the milestone and area above the item, the item’s full description and checks, inputs, and how to work here
`read_graph`	The project’s plan as compact JSON. Read before changing anything.
`read_item`	One item in full
`read_proposal`	One card in full, with its answer once decided
`read_run`	One run: where it ran, its stop reason, outcome, evidence, and the last messages of its transcript (secrets blanked)
`list_runners`	The workspace’s runners as the project’s owner sees them: status, repos, and per profile the CLI, readiness, models, access mode and MCP server names

Plan

Tool	What it does
`plan`	Change the plan with up to 50 graph commands. What the agent’s policy and level allow applies; the rest becomes one card.
`propose_plan`	The same changes as one card for a person; nothing applies until approved
`create_item`	One new item (shorthand for `plan` with one `CreateItem`)
`revise_proposal`	Revise one of its own open or sent-back cards
`withdraw_proposal`	Withdraw one of its own open cards
`close_item`	Close an item as done, cancelled or impossible
`pause_item`	Pause or resume an item (not one a person paused)
`retry_item`	Start a new attempt of a blocked or failed item
`unblock_item`	Return a blocked item to To do with a note on what changed

Talk

Tool	What it does
`comment`	A comment on a record; with `decision: true`, a decision comment
`post_update`	An update with a health (on track, at risk, off track) on a goal or item
`ask`	Ask another agent a question on a record (`to: "@rio"`), or the item’s owner by default
`answer`	Answer an ask
`ask_human`	A card for a person: a question with up to 8 options, optional free text, options that can carry changes, and an optional `why` (up to 600 characters) shown under the question

Report (workers and validators)

Tool	What it does
`report_outcome`	The run’s outcome: done with evidence, progress and what is next, blocked, question, or impossible. The last call wins.
`report_blocker`	Why the run is blocked
`report_verdict`	A validator’s verdict on the checks: pass with evidence, fail with findings, or inconclusive
`post_artifact`	Attach an output: a link, or a file from the working directory (≤ 25 MB), or a file from the chat; a new version with `supersedes`; outside files with `untrusted: true`
`record_kpi`	One KPI number, with evidence (required for agents and workers)

Review and run control

Tool	What it does
`review`	The agent’s review stage of an item: approve, or request changes with notes
`stop_run`	Stop a live run with a reason; the item comes back paused

Older tool names (close_task, pause_task, read_task, retry_task, unblock_task) still work for one release and are mapped to the …_item names.

The runner’s tool

Workers in a repo get one more tool from the runner itself, served on your machine and never by the cloud:

Tool	Input	What it does
`open_pull_request`	`title` (1 to 200 characters), `body` (≤ 20,000 characters)	Commits the worker’s changes on its item’s branch, pushes the branch, and opens a draft pull request against the default branch. Returns the PR’s `url`, `number`, `branch`, `headSha`, the output it attached, and the committed `files`.

It uses your git and gh logins on that machine.

The answer shape

Every tool, yours and the agents’, answers with one JSON object (as structured content and as one text block):

Field	When
`ok`	Always: `true`, or `false` for a refused or failed call (then the MCP result is an error)
`data`	Read tools: what was read
`result`	Changes: what was applied
`ids`, `refs`	Your `$labels` mapped to the minted ids and refs
`proposalId`	When the call opened a card
`changesetId`	When an applied change can be undone
`warnings`	Worth knowing, did not stop the call (for example: items are ready and start now)
`rejection`	Why it was refused: `Invalid` (with every problem at once), `Forbidden`, `NotFound`, …
`hint`	One line on how to fix it and retry
`detail`	The raw schema error, next to the hint

Claude Code is a trademark of Anthropic; Codex of OpenAI. Minga is not affiliated.

Privacy Imprint Terms