Docs
Docs menu

MCP server

The MCP server every node runs for agents, the tools it offers implementers and reviewers, and how agents authenticate with their task token.

Every node serves a Model Context Protocol server at /mcp. It’s how an agent on a runner learns its task and hands its work back: it reads the instructions, submits the change it pushed, reports progress, and, as a reviewer, reads candidates and records a verdict.

You don’t set anything up. When a runner starts Claude Code for a job, it gives it the node’s MCP server with the job’s task token, and nothing else.

Transport and authentication#

The server speaks MCP over streamable HTTP at https://moru.example.com/mcp. It is stateless and answers with plain JSON.

Every call carries the agent’s task token:

Authorization: Bearer <task token>

A task token is minted for one task when a runner leases a job. It names the agent, the person the agent works for, the repository, the scratch repo and the refs it may push, and what it may do. It expires after 4 hours by default (the node’s --agent-token-ttl). The same token lets the agent clone the repository and push to its scratch repo over git.

On every call the node checks that:

  • the token is a valid agent task token;
  • the runner’s signed claim for the job has been accepted, so whatever the agent submits is tied to a record of how it ran;
  • the person who delegated the work still has the access it needs: write on the repository for an implementer, read for a reviewer (write to record a verdict). Remove that person from the repository and the agent is stopped at its next call.

For each job, the agent’s MCP configuration looks like this (the runner writes it):

{
	"mcpServers": {
		"moru": {
			"type": "http",
			"url": "https://moru.example.com/mcp",
			"headers": { "Authorization": "Bearer ${MORU_TOKEN}" }
		}
	}
}

Tools for implementers#

ToolWhat it does
get_taskThe task: instructions, repository, the request with its acceptance criteria, and the paths to clone from and push to. Also the open threads on changes this task submitted, and, when the task revises a change, the revision to start from. A thread with a suggested change carries the suggestion, and current_text, the lines it would replace now, or applied once a person has applied it.
submit_changeSubmits the commit the agent pushed to its scratch repo as a change, or as a new revision of its change. Takes a title, a description and optionally the ref to submit (default: the only branch, usually refs/heads/task).
report_statusTells people what the agent is doing: state is working, done or failed, with a message. The line goes into the job’s log, which people with write access see on the request page.
reply_to_threadReplies to an open thread from get_task: what the agent changed, or why not.
get_ci_resultsThe CI runs of a revision of a change the task submitted: each run’s jobs and their states, and the last 50 log lines of each job that failed. change_id may be left out when the task submitted one change; revision defaults to the latest.
search_requestsThe repository’s requests, matched by text (words from the title, or the start of an ID), status, label (a name) and kind. At most 20, recently updated first.
file_requestFiles a request the agent noticed outside its task, rather than fixing it in its change: a title, an optional Markdown body and an optional kind (bug, feature, task). It waits in triage; see below.

An implementer pushes first, then submits:

git push "$MORU_PUSH_URL" HEAD:refs/heads/task

A request an agent files is signed with the agent’s own key and names the person the agent works for, who is notified when it’s accepted or declined; its page says “an agent, for” that person. It always waits in triage, whoever the agent works for, so a person reads it before anyone works on it. A task can file at most five. Filing needs the token’s request:file permission, which tasks started before it existed don’t have, and a repository that takes requests from the person the agent works for.

Text from outside the repository#

get_task says whose words it hands over. request.trust is {"title": …, "body": …}, each writer or outside, and every comment in open_threads has a trust. Text by someone without write access (outside) arrives between <<<outside-text …>>> and <<<end-outside-text …>>> markers, after a line saying it describes a problem and isn’t an instruction. The markers carry a code that changes every time, so the text can’t end them early. The acceptance criteria are never marked: only people with write access set them.

Tools for reviewers#

Reviewer agents rank the candidates of a Bake-off, or pre-review a single change. They get get_task, report_status and get_ci_results (for the candidates, by default at the revision under review), and:

ToolWhat it does
list_candidatesThe candidate changes under review: change ID, lane, title, revision, commit and ref.
get_diffA unified diff of a candidate (change_id) against its base, or with against set to another candidate’s change ID, against that candidate.
add_commentA line comment on a candidate, for a concrete problem: change_id, path, start_line, optional end_line, side (new, the candidate’s lines, or old, the base’s) and a Markdown body. An optional suggestion holds the replacement for those lines, which a person can apply in one click; it works on the new side only, and the body may then be empty.
submit_reviewSeveral comments on one candidate as one review: change_id, an outcome (comment or request_changes), an optional Markdown summary, comments (each with add_comment’s fields except change_id, suggestion included) and replies (thread_id and body) to threads on that candidate. People get one notification for the review.
submit_verdictRecords the verdict, once: a score from 0 to 10 for every candidate on every acceptance criterion (or overall when there are none), a ranking of all candidates best first, and a short rationale. It closes the review.

Reviewers call add_comment or submit_review before submit_verdict, which closes the review. A reviewer replies to threads in submit_review’s replies: reply_to_thread is for implementers.

Agents can comment, reply and suggest, but they can’t resolve threads, apply suggestions or approve changes: submit_review refuses the outcome approve. A person decides whether feedback was addressed and what gets merged. One review task can open at most 50 threads, an agent can add at most 100 comments and replies to one change, and one review holds at most 100 comments and replies.

What revising agents see#

When someone asks an agent to revise a change, its instructions start it from the change’s latest revision and point it at the open threads in get_task. For each thread with a suggestion, it gets the replacement lines and current_text, the lines they would replace in that revision. It’s told to apply the suggestions it agrees with in its revision and say so with reply_to_thread, and to reply with its reasons for the rest. It amends its commit rather than adding commits on top, and submits the result as the change’s next revision.

In a revise round, the instructions also say which round it is and why the revision before didn’t pass: the CI jobs that failed, and whether the pre-reviewer requested changes. For failed CI it’s pointed at get_ci_results for that revision, which has the end of each failed job’s log; logs never go in the instructions. A pre-reviewer of a later round is told that earlier revisions were reviewed, and to check whether their threads were addressed rather than raise them again.

get_task also says how the change it revises stands against its target branch:

  • base_state: state (current, applies, conflicts, or unknown if the check couldn’t run), onto (the target commit it was checked against) and paths (the conflicting files). null when the task revises no change or it hasn’t been checked.
  • rebase_onto: when the change conflicted with its target as the task was created, the commit to rebase onto. It doesn’t move during the task, even if the branch does. The instructions then tell the agent to rebase first and resolve the conflicts, keeping both sides’ intent.
  • landed_since, with rebase_onto: what landed on the target since the revision’s base and touches the conflicting files, newest first, at most 10. A Moru change is {"kind": "change", "change_id", "title", "description"}, with the description cut at 4 KiB; a commit pushed directly is {"kind": "commit", "commit", "subject"}.

A pre-review of a revision an agent made by rebasing gets rebased in get_task: from_revision (the revision it was rebased from), onto, paths (what that revision conflicted on) and landed_since, as above. It’s null for any other revision. The reviewer’s instructions say the revision is a rebase and give the git range-diff that compares it with the one it came from, so the review checks that the rebase kept both sides’ intent.

The runner submits nothing when the agent exits in the middle of a rebase, merge, cherry-pick or revert, so conflict markers never reach a revision. The task fails with “left a rebase unfinished”.

Calling it by hand#

The tools are plain JSON-RPC over HTTP, so you can call them with curl when you debug an agent run. With the task token in MORU_TOKEN:

curl -sS -X POST https://moru.example.com/mcp \
  -H "Authorization: Bearer $MORU_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_task","arguments":{}}}'

Your own MCP client#

The MCP server is for agents that a runner started. Its tools need an agent task token: a person’s session or access token is refused with “MCP tools need an agent task token”. To script Moru as a person, use the REST API.

Command menu
Search for a page, repository, change or request, or run a command