Integrations
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#
| Tool | What it does |
|---|---|
get_task | The 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_change | Submits 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_status | Tells 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_thread | Replies to an open thread from get_task: what the agent changed, or why not. |
get_ci_results | The 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_requests | The 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_request | Files 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:
| Tool | What it does |
|---|---|
list_candidates | The candidate changes under review: change ID, lane, title, revision, commit and ref. |
get_diff | A unified diff of a candidate (change_id) against its base, or with against set to another candidate’s change ID, against that candidate. |
add_comment | A 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_review | Several 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_verdict | Records 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, orunknownif the check couldn’t run),onto(the target commit it was checked against) andpaths(the conflicting files).nullwhen 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, withrebase_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.