MCP Server

Maina includes an MCP (Model Context Protocol) server that exposes its engines to any MCP-compatible IDE — Claude Code, Cursor, Windsurf, and others.

Setup

The fastest path is one command — it auto-detects every supported client on your machine and writes the maina entry into each global config:

maina mcp add

To remove maina from every client just as quickly:

maina mcp remove

Or scope to specific clients:

maina mcp add --client claude,cursor,windsurf
maina mcp add --scope project          # write to .mcp.json / .claude/settings.json instead of global
maina mcp add --dry-run                # preview the writes without touching disk
maina mcp list                         # show install status per client

Supported clients: Claude Code, Cline, Codex, Continue, Copilot, Cursor, Gemini CLI, OpenHands, Roo Code, Windsurf, Zed AI (any MCP client works — those eleven are auto-detected). The command preserves all other MCP servers and unrelated keys via an atomic merge — safe to run repeatedly.

The launcher is auto-detected per machine, in this priority order:

Direct maina binary when @mainahq/cli is installed globally (bun install -g @mainahq/cli or npm install -g @mainahq/cli). Fastest by far — no package manager in the spawn path, no cold-start download, no cache races. Recommended.
Resolved bunx @mainahq/cli@<version> --mcp when Bun is available.
Resolved npx @mainahq/cli@<version> --mcp as the universal fallback.
Bare npx @mainahq/cli@<version> --mcp as the last-resort fallback when nothing else resolves on the install machine — entry stays syntactically valid; user can edit after installing Node or Bun.

Tiers 1-3 are written using the absolute resolved binary location (/opt/homebrew/bin/bunx, /Users/.../.bun/bin/maina, etc.) so MCP clients with stripped-PATH spawn contexts (Cursor, Zed, Claude Code desktop) can find them. Tier 4 is the only case where the bare command name is written. Manual examples below use npx for portability.

The setup wizard (maina setup) also writes the project-scoped configs (.mcp.json, .claude/settings.json, .cursor/mcp.json) for you using a keyed JSON merge — every existing mcpServers.* entry is preserved byte-for-byte and only the maina key is written. Safe to re-run; safe against hand-edited configs. Most users won’t need maina mcp add unless they want maina available in every project from any client.

Or configure manually per tool:

.claude/settings.json (auto-created by maina init):

{"mcpServers":{"maina":{"command":"npx","args":["@mainahq/cli","--mcp"]}}}

.cursor/mcp.json or .mcp.json:

{"mcpServers":{"maina":{"command":"npx","args":["@mainahq/cli","--mcp"]}}}

~/.codeium/windsurf/mcp_config.json:

{"mcpServers":{"maina":{"command":"npx","args":["@mainahq/cli","--mcp"]}}}

~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json (mac; .config/Code/... on Linux, %APPDATA%/Code/... on Windows):

{"mcpServers":{"maina":{"command":"npx","args":["@mainahq/cli","--mcp"]}}}

~/.codex/config.toml:

[mcp_servers.maina]
command = "npx"
args = ["@mainahq/cli", "--mcp"]

~/.continue/config.json under experimental.modelContextProtocolServers:

{"experimental":{"modelContextProtocolServers":[{"name":"maina","transport":{"type":"stdio","command":"npx","args":["@mainahq/cli","--mcp"]}}]}}

~/.gemini/settings.json:

{"mcpServers":{"maina":{"command":"npx","args":["@mainahq/cli","--mcp"]}}}

~/.config/zed/settings.json under context_servers:

{"context_servers":{"maina":{"source":"custom","command":{"path":"npx","args":["@mainahq/cli","--mcp"]}}}}

Not yet handled by maina mcp add. Configure manually under each tool’s mcpServers block:

{"mcpServers":{"maina":{"command":"npx","args":["@mainahq/cli","--mcp"]}}}

(.roo/mcp.json for Roo Code; .amazonq/mcp.json for Amazon Q.)

No plugins, no extensions, no separate server process.

Tools — progressive disclosure

By default the MCP server registers three high-value tools + one discovery meta-tool at handshake, keeping the capability payload that every session streams to the host small:

Default (handshake)	Description	Engine
`verify`	Run the verification pipeline on staged or specified files. Returns findings with severity and location.	Verify
`getContext`	Get focused codebase context for a command. Returns context assembled from the relevant layers with token budget applied.	Context
`reviewCode`	Run two-stage review on a diff — spec compliance first, then code quality.	Verify + Prompt
`list_tools`	Enumerate every MCP tool the server could expose, for capability discovery. Returns the full 10-tool catalogue without registering them.	Server

Opt in to the full 10-tool surface with --all-tools. In this mode list_tools is no longer registered (it was only relevant when the remaining seven were hidden):

maina --mcp --all-tools
# or via createMcpServer({ allTools: true })

Extended (only with `--all-tools`)	Description	Engine
`getConventions`	Get the project constitution and conventions. Returns `.maina/constitution.md` content.	Prompt
`checkSlop`	Check code for AI-generated slop patterns (filler words, hallucinated imports, dead code).	Verify
`explainModule`	Get a Mermaid dependency diagram for a directory. Visualizes module structure and cross-file references.	Context
`suggestTests`	Generate TDD test stubs from a plan.md file. Returns test code with red-green annotations.	Prompt + Context
`analyzeFeature`	Check spec/plan/tasks consistency for a feature. Reports mismatches and orphaned artifacts.	Context
`wikiQuery`	Search and synthesize answers from codebase wiki. Returns AI-generated answer with source citations.	Context (L5)
`wikiStatus`	Wiki health dashboard — article counts, coverage, staleness.	Context

DeepWiki compat — three additional tools are registered alongside the 10 when --all-tools is on, preserving wire-compatibility with DeepWiki clients:

DeepWiki-compat	Description	Engine
`ask_question`	Ask the wiki an open-ended question.	Context (L5)
`read_wiki_structure`	Return the wiki’s article index — titles, types, paths.	Context
`read_wiki_contents`	Fetch the full markdown of a named wiki article.	Context

Set MAINA_MCP_STRICT_TEN=1 to prune DeepWiki from the --all-tools surface when you need an exact 10-tool handshake (for comparison tests, for example).

Why progressive: every tool description is streamed to the host on every session start, and that payload burns conversation context before any real work happens. Three tools at handshake is enough for the most common flows; agents that need the rest can call list_tools to discover them and ask the user to relaunch with --all-tools.

How It Works

IDE (Claude Code, Cursor, etc.)
  |
  |  MCP protocol (JSON-RPC over stdio)
  |
  v
maina --mcp
  |
  +-- getContext -------> Context Engine (4 layers, dynamic budget)
  +-- getConventions ---> Prompt Engine (constitution + custom prompts)
  +-- verify -----------> Verify Engine (full pipeline)
  +-- checkSlop --------> Verify Engine (slop detector)
  +-- reviewCode -------> Verify Engine (two-stage review)
  +-- explainModule ----> Context Engine (semantic layer + tree-sitter)
  +-- suggestTests -----> Prompt Engine + Context Engine
  +-- analyzeFeature ---> Context Engine (cross-artifact analysis)
  +-- wikiQuery -------> Context Engine (L5 wiki layer)
  +-- wikiStatus ------> Context Engine (wiki health)
  |
  +-- Cache (all tools respect the 3-layer cache)

Every tool call goes through the same engines as the CLI commands. The cache ensures repeated queries return instantly.

Context in Your IDE

With the MCP server running, your IDE’s AI assistant gains:

Codebase awareness — getContext provides the same 4-layer context the CLI uses, so the AI sees relevant code, not everything.
Convention enforcement — getConventions injects your constitution into every interaction.
Inline verification — verify and checkSlop catch issues as you write, not after you commit.
Review on demand — reviewCode gives you the same two-stage review the CLI provides, inside your editor.
Test suggestions — suggestTests generates TDD stubs from your plan files.
Wiki search — wikiQuery searches compiled codebase knowledge and returns AI-synthesized answers with citations.

The MCP server is the same three engines, accessible from any tool that speaks MCP.