MCP Server
The provisioning, tool catalog, authentication, and lazy-loading policy of the self-hosted moai mcp-server (a stdio local MCP server) provided by MoAI-ADK.
MoAI-ADK rides on top of the Claude Code MCP ecosystem, then adds its own MCP server on top of that. A single binary (moai mcp-server) runs as a stdio local server, exposing MoAI-ADK-specific tools — SPEC lifecycle audit, verification snapshots, the goal engine, cross-model audit, codex/GLM delegation — to the Claude Code runtime.
Relationship between the two MCP docsClaude Code generic MCP covers the platform’s own MCP (Model Context Protocol) integration — the USB-port analogy, server registration, transport types, the
/mcpcommand, OAuth authentication, and the lazy-loading principle.This document covers the MoAI self-hosted MCP server that sits on top of it. The two surfaces share the same core rules, but they cover different subjects.
The Claude Code MCP ecosystem and MoAI’s self-hosted MCP server are separate servers, yet they rest on identical operating principles. They share three core rules.
| Core rule | Meaning |
|---|---|
| MCP-over-CLI | The same capability is exposed both as a CLI and as an MCP tool, but when the MCP tool is in the agent’s tools: list, the MCP path is preferred over the CLI. It offers structured output, avoidance of shell-quoting, and low latency inside subagents. |
| Lazy loading | MCP tool definitions are lazy-loaded by default. Normally only short metadata sits in the context, and the schema is loaded via ToolSearch at the moment of an actual call. |
| Permission gate | MCP tools pass through the same permission gate as Claude’s ordinary tools. On the first call, an approval prompt surfaces in the main session, and once allowed, subsequent calls to the same tool do not ask again. |
flowchart TD
CC["Claude Code runtime
(tool permission · lazy loading · approval)"]
CMCP["Generic MCP server
(context7, chrome-devtools, …)"]
MMCP["moai mcp-server
(MoAI self-hosted tools)"]
CC --> CMCP
CC --> MMCP
MMCP --> TOOLS["SPEC lifecycle · verification · goal · audit · codex/GLM delegation"]
CMCP --> EXT["External tools (library docs · browser automation · …)"]The key point is that “MoAI does not provision MCP” is a half-truth. It is true that external MCP servers (context7, playwright, etc.) are not provisioned by default. But the one MoAI self-hosted server is installed as default-on at moai init time. This server is the channel through which MoAI’s tool catalog reaches Claude Code.
moai init creates .mcp.json (project scope) at the project root and places exactly one active entry inside it — the self-hosted moai local stdio server.
{
"mcpServers": {
"moai": {
"command": "moai",
"args": ["mcp-server"]
}
},
"staggeredStartup": {
"enabled": true,
"delayMs": 500,
"connectionTimeout": 15000
}
}staggeredStartup is a Claude Code runtime field that regulates servers so they start sequentially. When there are multiple servers, it prevents a simultaneous-startup race.
The distribution default activates only the moai server. Five external servers are documented but disabled, and are turned on with the moai mcp add <name> command.
| Server | Purpose | Activation |
|---|---|---|
context7 | Looking up official up-to-date library docs (resolve-library-id, get-library-docs) | moai mcp add context7 |
chrome-devtools | Headless browser automation | moai mcp add chrome-devtools |
playwright | Browser automation + E2E testing | moai mcp add playwright |
ast-grep | Structural code search and refactoring | moai mcp add ast-grep |
aside | Optional browser agent that works inside a logged-in browser (exec, repl) | moai mcp add aside --command aside --args mcp --scope user |
aside is optional. It is not part of the default configuration, and no workflow depends on it. To register it for every project, run moai mcp add aside --command aside --args mcp --scope user; omit --scope user to register it for the current project only. aside mcp exposes two tools: exec runs the browser agent on logged-in sites, and repl runs Playwright-style JavaScript against open pages. Because it works inside the operator’s own logged-in browser, MoAI uses it read-only by default and never with --permission full-access. aside repl has no permission flag, so read-only use of the REPL is an operating rule, not something the tool enforces. Any state-changing step needs the operator’s explicit confirmation, which only the MoAI orchestrator (never a subagent) asks for and runs. MoAI never installs Aside; to add Aside’s own browser skill, the operator runs aside skills install themselves. In the E2E workflow Aside is used only when /moai e2e --tool aside is passed explicitly (unavailable when CI=true), and when Aside is absent the workflow continues silently on the platform default toolchain.
.mcp.json is a git-tracked file. Therefore, “entries that carry secrets, entries that require credentials, and entries that fail the neutrality check” are forbidden. Every environment-variable value is written as a ${VAR} literal — the Claude Code runtime expands the actual value, so interpreted secrets are never serialized into the git-tracked .mcp.json.
{
"remote-needs-auth": {
"type": "http",
"url": "https://mcp.example.com/sse",
"headers": {
"Authorization": "Bearer ${MY_API_KEY}"
}
}
}${MY_API_KEY} is filled by the runtime from the environment variable. Only the literal string remains in the file itself, so the secret is never exposed in the repository.
Users never hand-edit .mcp.json. The moai mcp add|remove|list CLI manages the file, and this CLI operates through an atomic-RWM seam (flock file locking + compare-retry + backup-before-write + idempotent-skip). Even if two sessions edit simultaneously, one side’s change does not overwrite the other.
Thirty-three tools accept an optional project_root string: spec_progress, spec_audit, spec_drift, verify_snapshot, verify_trend, codex_audit, codex_review, glm_audit, glm_review, claude_audit, audit_multi, graph_file_api, graph_find_code, graph_shortest_path, graph_trace_calls, factory_decide, todo_add, todo_list, factory_next, factory_stage, factory_complete, factory_renew, audit_cache, glm_job_cancel, glm_job_result, glm_job_status, glm_task, goal_arm, goal_status, jev_ask, fetch_web, session_list, and todo_claim. It names the tree the call should act on, and the value to pass is the caller’s own git rev-parse --show-toplevel. On factory_next, factory_stage, factory_complete, and factory_renew the input is required rather than optional — pass your own toplevel or the call is refused; it is never defaulted.
An agent working inside a worktree must pass it. This is not a convenience. The server has no way to work the answer out for itself: it is a long-lived subprocess, so its working directory cannot follow a worktree switch, and the environment variable it falls back on names the project root — the primary checkout — even for a session working in a worktree. Omit it from a worktree and the call acts on the primary checkout instead, which means a SPEC that exists only on the card’s branch is not in the catalog the auditor reads. It is not reported missing. It is simply absent.
The caller is the only party that holds the answer. That is why it is an input rather than something inferred.
| Situation | What to pass | What happens |
|---|---|---|
| Session in a worktree | project_root: <git rev-parse --show-toplevel> | the call acts on that tree |
| Session in the primary checkout | nothing | resolves exactly as it always has |
Linked worktree of a repository that does not track .moai (the worktree has no .moai of its own) | project_root: <git rev-parse --show-toplevel> | accepted when git lists it as a worktree of a primary checkout that has .moai; the call acts on the worktree |
| Path that is not a MoAI project root | — | the call is rejected with an error naming the path |
The rejection is deliberate, not a rough edge. A silent fallback to the default would send a caller who mistyped its own worktree path back to auditing the primary checkout while reporting success — the exact failure the parameter exists to prevent.
A linked worktree of a repository that keeps .moai out of git has no .moai of its own, and it is still accepted — but only when the path is the top level of a worktree that git worktree list registers and the repository’s primary checkout has .moai. A subdirectory, an unregistered or prunable worktree, an ambiguous layout such as a separate git directory, or a machine where git is unavailable is rejected. On such a worktree, when it has no workflow config of its own, the explicit audit gate (workflow.audit.gates) is read from the primary checkout; when the primary cannot be identified, the gate is treated as required, so a missing verdict fails rather than passes. The SPEC catalog (spec_progress, spec_drift, spec_audit) answers over the union of the worktree’s and the primary checkout’s .moai/specs, and every record and finding names its source (worktree or primary); a SPEC ID present in both is counted once, from the worktree copy, and the shadowed primary copy is named in the response. State — audit receipts, auditor start markers and rejections, audit_multi convergence results, and verify_snapshot snapshots — is kept in the primary checkout’s .moai/state under the worktree’s own tree identity, so trees sharing one store never replace each other’s records; _root.worktree_warning and _root.sources report what was actually read. When the primary checkout cannot be identified, state writes are not redirected anywhere: they fail with an error (best-effort writes are skipped, with a notice saying so), and the catalog reads the worktree only, with _root stating why the primary was not read. Because the audit gate is then treated as required, phase-entry spawns from that worktree are denied even in a repository that never enabled the gate; make the primary identifiable, or give the worktree its own .moai/config/sections/workflow.yaml, to release them.
For audit_multi the root reaches both backends of the fan-out: codex receives it as the directory it reviews in, and the GLM path uses it to collect the diff it sends to z.ai. Passing it is what keeps the two secondary opinions about the same tree — without it they can review different ones.
Version caveat: a server that is already running keeps the old behavior until it restarts, even after the binary underneath it is replaced — a subprocess does not reload itself. What a caller can check is whether project_root appears in the ListTools response.
The tools exposed by moai mcp-server are summarized below by family. At call time they all carry the mcp__moai__ prefix. This page does not state a tool count. The authoritative count and list are what the installed binary returns from tools/list, documented in .claude/rules/moai/core/moai-mcp-tools.md; where either differs from this page, follow them.
| Tool | Purpose | Consumer agent | CLI equivalent |
|---|---|---|---|
mcp__moai__spec_progress | List SPEC documents + frontmatter | manager-spec, manager-docs | — |
mcp__moai__spec_audit | SPEC lifecycle audit (era classification + drift) | manager-spec, manager-docs, plan-auditor, super-advisor | moai spec audit |
mcp__moai__spec_drift | Modern-era V3R6 drift findings | manager-spec, plan-auditor | moai spec audit (drift view) |
Used in the plan phase (when manager-spec authors a new SPEC, checking era classification and drift) and the sync phase (when manager-docs verifies lifecycle closure). plan-auditor performs skeptical plan-phase review with spec_audit / spec_drift.
| Tool | Purpose | Consumer agent | CLI equivalent |
|---|---|---|---|
mcp__moai__verify_snapshot | Read/record per-key verification snapshots | manager-develop | moai verify check |
mcp__moai__verify_trend | Per-key verification history trend | manager-develop, sync-auditor, super-advisor | moai verify check |
Used by manager-develop during run-phase self-verification (attribution seam §E), and by sync-auditor and super-advisor to review trends. verify_snapshot reads or records snapshots keyed by the HEAD digest, and verify_trend surfaces the history for judging convergence.
| Tool | Purpose | Consumer agent | CLI equivalent |
|---|---|---|---|
mcp__moai__goal_arm | Arm a condition-declared goal | orchestrator main session ONLY (wired to no agent) | moai goal arm / /moai goal |
mcp__moai__goal_status | Read armed-goal state | manager-develop, manager-lead | moai goal status |
mcp__moai__session_list | List active moai sessions | manager-lead | moai session list |
goal_arm is orchestrator-only — arming an autonomous loop is an orchestrator concern, so it is never called inside an agent. This is a design decision to preserve the flat-hierarchy arming surface. goal_status is the channel through which manager-develop / manager-lead read the progress of the armed condition, and session_list is a race-mitigation tool for manager-lead to detect concurrent sessions on the same checkout before fan-out.
| Tool | Purpose | Consumer agent | CLI equivalent |
|---|---|---|---|
mcp__moai__audit_multi | Multi-auditor convergence (claude + codex + glm) | plan-auditor, sync-auditor | — (MCP-only convergence entry point) |
mcp__moai__claude_audit | Single Claude-subscription backend audit (claude -p, read-only isolation, structured output) | plan-auditor, sync-auditor; called automatically by audit_multi in GPT/GLM sessions | — |
mcp__moai__codex_audit | codex backend single audit (native/adversarial) | plan-auditor, sync-auditor | — |
mcp__moai__glm_audit | GLM (z.ai) backend single audit | plan-auditor, sync-auditor | — |
mcp__moai__audit_cache | plan-audit PASS cache (compute_hash / lookup / store, process-shared) | sync-auditor | — |
The single-backend audit mode is determined by the project’s audit_model setting: codex+glm (default, converges via audit_multi) | glm | codex | none (Claude-only, no backend call). All backends are fail-open — an unavailable backend returns inconclusive, never a Go error.
| Tool | Purpose | Consumer agent | CLI equivalent |
|---|---|---|---|
mcp__moai__codex_review | codex review of the caller’s own change — scope: card (the card diff) or scope: uncommitted | the main session; any agent whose tools: list names it | moai verify codex-review (codex leg only) |
mcp__moai__glm_review | GLM (z.ai) review of the caller’s own change, sent as a diff | the main session; any agent whose tools: list names it | — |
Neither is an audit tool. A result is advisory and non-binding: advisory is always true, no audit receipt is filed or read, and the required conversion of workflow.audit.gates.* never applies (an absent reviewer yields inconclusive, not fail). The audit model pins are not applied either, so model is whatever the caller passes or the backend default. scope is required and has no default. card resolves the card diff through the same scope resolver the turn-end review gate uses, recomputing the merge base on every call; a tree that is not a card worktree returns inconclusive without reviewing anything. uncommitted reviews the uncommitted changes of the named tree — in the primary checkout that is the whole shared working tree, and there is no path restriction. Every result carries scope, base (the merge-base SHA for card, an empty string otherwise), backend, and tree (the canonical root that was actually reviewed).
GLM has no filesystem, so the request carries a diff with the runtime-managed paths left out. Untracked files cannot be part of a diff and are listed in excluded_untracked; a diff cut at the size cap sets truncated; an empty diff calls neither backend. A call is synchronous, finishes within the review budget, and sends no progress notifications. A server process that started before these tools existed does not list them, so reconnect it. In the meantime the codex leg can fall back to moai verify codex-review --project-root <tree>; the GLM leg has no fallback.
| Tool | Purpose | Consumer agent | CLI equivalent |
|---|---|---|---|
mcp__moai__codex_setup | Probe local codex install (LookPath + version + auth) | super-advisor | — |
The general codex delegation family (codex_task, codex_job_status / codex_job_result / codex_job_cancel) was removed; codex_setup stays as the audit surface’s install probe, wired into super-advisor — the on-demand high-reasoning consultation agent. codex is optional — if it is missing or unavailable, it returns fail-open inconclusive, never a hard error.
| Tool | Purpose | Consumer | CLI equivalent |
|---|---|---|---|
mcp__moai__codex_role_audit | Start one read-only role as a top-level codex exec process (read-only sandbox, every MCP server disabled); returns a job id at once | Codex session | — |
mcp__moai__codex_role_audit_status | Read a role job’s state and timestamps | Codex session | — |
mcp__moai__codex_role_audit_result | Read a finished role job’s exit code, returned text or verdict path, and launch record path | Codex session | — |
A Codex session starts read-only roles such as plan-auditor and sync-auditor through this family rather than through spawn_agent. There is no CLI equivalent, because a nested codex exec inside a Codex session’s shell cannot reach the model. Jobs live in the server process and end with it.
| Tool | Purpose | Consumer agent | CLI equivalent |
|---|---|---|---|
mcp__moai__glm_task | Delegate a task (arbitrary prompt) to GLM (z.ai) (sync or background) | manager-develop, super-advisor | — (no such CLI) |
mcp__moai__glm_job_status | Read a background GLM job’s status/record | manager-develop, super-advisor | — |
mcp__moai__glm_job_result | Read a background GLM job’s output | manager-develop, super-advisor | — |
mcp__moai__glm_job_cancel | Stop a running background GLM job | manager-develop, super-advisor | — |
The GLM delegation family is wired into super-advisor and manager-develop in the same shape as the codex delegation family. manager-develop carries the whole family; it delegates bounded mechanical subtasks with glm_task only as the External Model Delegation section of the run workflow allows, and a GLM job sends its prompt to an external provider. glm_task returns the completed text as-is when background is false, and returns a job ID immediately when true (observed and cancelled afterwards with glm_job_status · glm_job_result · glm_job_cancel). The response token ceiling can be overridden with max_tokens; a default ceiling is set on the server side. Background jobs live inside the server process, so they end with it. GLM is optional too — a missing key or an unreachable z.ai returns a structured fail-open result, never a tool error.
| Tool | Purpose | Consumer | CLI equivalent |
|---|---|---|---|
mcp__moai__graph_file_api | List one source file’s exported declarations with signatures (no bodies) | any agent | — |
mcp__moai__graph_find_code | Search the code-derived edge layer for a symbol’s call sites and callers (each edge carries its resolution confidence) | any agent | — |
mcp__moai__graph_trace_calls | Trace call edges from a symbol toward callers and callees, up to a given depth | any agent | — |
mcp__moai__graph_shortest_path | Shortest call path between two symbols (at most 8 hops, each with its line and confidence) | any agent | — |
Every answer names the tree root and commit it was computed from. The edge layer is the edges.jsonl built by moai graph build.
| Tool | Purpose | Consumer | CLI equivalent |
|---|---|---|---|
mcp__moai__jev_ask | Ask typed questions over one supplied state and receive typed answers with probabilities | unavailable at the shipped default (workflow.jev.enabled: false) | — (MCP-only) |
The tool is always registered, but with the gate off it builds no request and makes no network call. Its answer is a signal for a person to read, and on its own it is never a completion verdict, merge approval, or queue mutation. Where software uses it automatically, it is only as a signal — for example the order in which moai todo --auto considers queued cards, or an optional Kickoff cross-check that can only confirm or hand over to a person.
When the MCP tool is in the agent’s tools: list, the MCP path is preferred over the CLI. The two paths run the same implementation underneath. The MCP path is advantageous for three reasons:
- It returns structured output (no parsing needed)
- It avoids shell-quoting hazards
- It runs with low latency in environments where Bash may be restricted inside a subagent
The CLI is used only when the MCP tool is not in the tools: list, or when the CLI form reads more naturally from the main session.
When running in a GLM session (moai glm), web search and web fetch are routed to z.ai MCP tools instead of the built-in WebSearch / WebFetch. Authentication is read from ~/.moai/.env.glm.
The z.ai MCP servers (zai-mcp-server, web_search_prime, web_reader) are disabled by default and are turned on with moai glm tools enable in a GLM session. For the routing rules inside a GLM session, see Multi-LLM backends.
The codex audit / delegation tools (codex_audit, codex_task, etc.) read authentication credentials from ~/.codex/auth.json. codex is optional — if the auth file is absent or codex is not installed, the relevant tools return inconclusive and continue. The design ensures that agent work is never coupled to codex availability.
GLM, codex, and Claude — all three backends follow the fail-open principle. An unavailable backend returns inconclusive and never raises a Go error. If one backend drops out, the audit converges with the rest, and if no backend is available at all, Claude runs alone (audit_model: none).
Among the codex and GLM delegation tools, codex_task and glm_task can start a background job with background: true. In this case they return a job ID immediately without waiting for the job to finish.
Progress is polled with two tools (below is the codex example — for GLM, glm_job_* plays the same role):
codex_task(background=true) ──▶ returns job ID
│
├── codex_job_status(job ID) ──▶ running / completed / failed
│
└── codex_job_result(job ID) ──▶ read output on completion
If needed, codex_job_cancel(job ID) ──▶ cancelThe per-tool configuration and authentication status can be checked in the MCP console (web console). For detailed console features, see Web console.
MoAI’s self-hosted MCP server also follows the same lazy-loading principle as the Claude Code generic MCP. Loading the full tool definitions into the context at all times fills the context window quickly, so normally only short metadata is kept and the schema is loaded at the moment of an actual call.
To call a deferred tool, you must first load its schema into the active context with ToolSearch.
tool needed ──▶ {is the schema in context?}
│
┌──────┴──────┐
no yes
│ │
preload schema call the tool
via ToolSearch
│
└──▶ call the toolIf you skip this step, the tool call is rejected with a validation error. For background on the lazy-loading principle, see the “Lazy loading and Tool Search” section of the Claude Code generic MCP document.
- Claude Code generic MCP — the platform’s own MCP integration (USB-port analogy, server registration, transport types, the
/mcpcommand) - Multi-LLM backends — operating the Claude × GLM multi-backend · the rule by which web search/fetch in a GLM session routes to z.ai MCP tools
- Cross-model audit — the multi-auditor convergence mechanism
- Web console — the per-MCP-tool configuration and authentication surface