Skip to main content

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.

UPDATED 2026-10-29 17 min read EDIT ON GITHUB ↗

MCP Server

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 docs

Claude Code generic MCP covers the platform’s own MCP (Model Context Protocol) integration — the USB-port analogy, server registration, transport types, the /mcp command, 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.

Same core, two surfaces

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 ruleMeaning
MCP-over-CLIThe 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 loadingMCP 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 gateMCP 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.

.mcp.json provisioning

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.

json
{
  "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.

Five documented-but-disabled entries

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.

ServerPurposeActivation
context7Looking up official up-to-date library docs (resolve-library-id, get-library-docs)moai mcp add context7
chrome-devtoolsHeadless browser automationmoai mcp add chrome-devtools
playwrightBrowser automation + E2E testingmoai mcp add playwright
ast-grepStructural code search and refactoringmoai mcp add ast-grep
asideOptional 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.

Neutrality contract

.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.

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.

atomic-RWM management

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.

The project_root input — the caller names its own tree

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.

SituationWhat to passWhat happens
Session in a worktreeproject_root: <git rev-parse --show-toplevel>the call acts on that tree
Session in the primary checkoutnothingresolves 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.

Tool catalog

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.

SPEC lifecycle

ToolPurposeConsumer agentCLI equivalent
mcp__moai__spec_progressList SPEC documents + frontmattermanager-spec, manager-docs—
mcp__moai__spec_auditSPEC lifecycle audit (era classification + drift)manager-spec, manager-docs, plan-auditor, super-advisormoai spec audit
mcp__moai__spec_driftModern-era V3R6 drift findingsmanager-spec, plan-auditormoai 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.

Verification snapshots

ToolPurposeConsumer agentCLI equivalent
mcp__moai__verify_snapshotRead/record per-key verification snapshotsmanager-developmoai verify check
mcp__moai__verify_trendPer-key verification history trendmanager-develop, sync-auditor, super-advisormoai 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.

Goal + session (autonomous loop)

ToolPurposeConsumer agentCLI equivalent
mcp__moai__goal_armArm a condition-declared goalorchestrator main session ONLY (wired to no agent)moai goal arm / /moai goal
mcp__moai__goal_statusRead armed-goal statemanager-develop, manager-leadmoai goal status
mcp__moai__session_listList active moai sessionsmanager-leadmoai 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.

Cross-model audit (second opinion)

ToolPurposeConsumer agentCLI equivalent
mcp__moai__audit_multiMulti-auditor convergence (claude + codex + glm)plan-auditor, sync-auditor— (MCP-only convergence entry point)
mcp__moai__claude_auditSingle 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_auditcodex backend single audit (native/adversarial)plan-auditor, sync-auditor—
mcp__moai__glm_auditGLM (z.ai) backend single auditplan-auditor, sync-auditor—
mcp__moai__audit_cacheplan-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.

On-demand self-review (advisory)

ToolPurposeConsumer agentCLI equivalent
mcp__moai__codex_reviewcodex review of the caller’s own change — scope: card (the card diff) or scope: uncommittedthe main session; any agent whose tools: list names itmoai verify codex-review (codex leg only)
mcp__moai__glm_reviewGLM (z.ai) review of the caller’s own change, sent as a diffthe 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.

codex delegation (background jobs)

ToolPurposeConsumer agentCLI equivalent
mcp__moai__codex_setupProbe 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.

codex read-only roles

ToolPurposeConsumerCLI equivalent
mcp__moai__codex_role_auditStart one read-only role as a top-level codex exec process (read-only sandbox, every MCP server disabled); returns a job id at onceCodex session—
mcp__moai__codex_role_audit_statusRead a role job’s state and timestampsCodex session—
mcp__moai__codex_role_audit_resultRead a finished role job’s exit code, returned text or verdict path, and launch record pathCodex 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.

GLM delegation (background jobs)

ToolPurposeConsumer agentCLI equivalent
mcp__moai__glm_taskDelegate a task (arbitrary prompt) to GLM (z.ai) (sync or background)manager-develop, super-advisor— (no such CLI)
mcp__moai__glm_job_statusRead a background GLM job’s status/recordmanager-develop, super-advisor—
mcp__moai__glm_job_resultRead a background GLM job’s outputmanager-develop, super-advisor—
mcp__moai__glm_job_cancelStop a running background GLM jobmanager-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.

Code queries

ToolPurposeConsumerCLI equivalent
mcp__moai__graph_file_apiList one source file’s exported declarations with signatures (no bodies)any agent—
mcp__moai__graph_find_codeSearch 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_callsTrace call edges from a symbol toward callers and callees, up to a given depthany agent—
mcp__moai__graph_shortest_pathShortest 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.

Judgment (gated, display-only)

ToolPurposeConsumerCLI equivalent
mcp__moai__jev_askAsk typed questions over one supplied state and receive typed answers with probabilitiesunavailable 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.

MCP-over-CLI rule

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.

Authentication

GLM (z.ai)

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.

codex

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.

All backends are fail-open

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).

Background job progress tracking

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):

text
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) ──▶ cancel

The per-tool configuration and authentication status can be checked in the MCP console (web console). For detailed console features, see Web console.

Lazy loading and ToolSearch

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.

text
tool needed ──▶ {is the schema in context?}
                           │
                    ┌──────┴──────┐
                    no             yes
                    │              │
            preload schema         call the tool
            via ToolSearch
                    │
                    └──▶ call the tool

If 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 /mcp command)
  • 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