The gap the MCP server fills
An AI coding agent is a text generator with a tool loop. It can read a file, edit a file, run a command, and read the output. The thing it cannot do, on its own, is honestly grade its own work — the model that hallucinated the diff is the same model that grades the diff, and a self-grade without an external anchor drifts toward a confident 8/10 on everything.
The Model Context Protocol is the open standard that lets the agent call an external tool over a local subprocess. The transport for local IDE integrations is stdio: the agent spawns the tool as a child process, writes JSON-RPC requests to its stdin, reads JSON-RPC responses from its stdout. The benefit is that the tool inherits the agent's environment — no separate daemon to launch, no auth dance, no port conflict — and the failure mode is the same as any other subprocess crash.
CodeOtter's MCP server is the same shape. The CLI is invoked as node tui/codeotter.mjs mcp, which switches the entry point from "run one review and exit" to "listen on stdio forever." The MCP client (the AI coding agent) holds the child process open for the lifetime of the integration and speaks JSON-RPC on its stdin and stdout. There is no HTTP server, no Socket and no port, and the MCP transport itself makes no network calls.
This post walks the wire-level contract.
The mcp subcommand and the JSON-RPC handshake
The CLI exposes five subcommands plus a TUI default:
codeotter tui # Connected repositories, scores and summaries (terminal default) codeotter review # Review local git diff (default outside a terminal) codeotter pr <url-or-number> # Review and score a GitHub / Forgejo / Gitea Pull Request codeotter ci # Run automated CI gate checks with merge blocker exit codes codeotter mcp # Start Model Context Protocol (MCP) server over stdio codeotter help # Show this help message
mcp calls startMcpServer(), which wires node:readline to process.stdin and a send(response) helper to process.stdout:
const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false });
function send(response) {
process.stdout.write(JSON.stringify(response) + "\n");
}
rl.on("line", async (line) => {
if (!line.trim()) return;
let req;
try { req = JSON.parse(line); } catch { return; }
const { id, method, params } = req;
// dispatch on `method`...
});
That is the entire transport. One readline interface, one send helper, one dispatch loop. Each line of stdin is parsed as a JSON-RPC 2.0 envelope; each response is a single line of newline-delimited JSON on stdout. The framing matches the official MCP TypeScript SDK's stdio transport.
The handshake responds to the initialize method with the canonical MCP server identity:
// request
{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { ... } }
// response
{
"jsonrpc": "2.0", "id": 1,
"result": {
"protocolVersion": "2024-11-05",
"capabilities": { "tools": {} },
"serverInfo": { "name": "codeotter-mcp", "version": "0.6.0" }
}
}
protocolVersion: "2024-11-05" is the MCP spec version this build speaks. serverInfo.version is the CLI's own VERSION constant, read from the package's package.json at startup, so an agent that lists MCP servers can see the build it is talking to. capabilities: { tools: {} } declares that the server implements the tools capability and nothing else (no resources, no prompts — those would be additive, not part of the v1 surface).
After the handshake, the client sends notifications/initialized (no response expected) and the server is live.
The two tools: codeotter_review_diff and codeotter_get_gates
The server implements exactly two tools on the tools capability. Both are declared in response to tools/list:
// request
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }
// response
{
"jsonrpc": "2.0", "id": 2,
"result": {
"tools": [
{
"name": "codeotter_review_diff",
"description": "Review a git diff or pull request with CodeOtter's engines: System One scores and gates when configured, language-model findings with a self-check.",
"inputSchema": {
"type": "object",
"properties": {
"diff": { "type": "string", "description": "Git diff content" },
"title": { "type": "string", "description": "PR or change title" },
"body": { "type": "string", "description": "PR or change description" }
},
"required": ["diff"]
}
},
{
"name": "codeotter_get_gates",
"description": "List the standard CodeOtter pre-merge gates and scoring rubrics.",
"inputSchema": { "type": "object", "properties": {} }
}
]
}
}
The two tools are deliberately minimal:
codeotter_review_diffis the do-the-work tool. It takes adiff(required) and optionaltitle/body, and runs the fullrunReviewpipeline — the same code path thereview,prandciCLI subcommands use. It returns the entirerunReviewpayload as a JSON-RPCcontent: [{ type: "text", text: <json> }]result.codeotter_get_gatesis the inspect-the-contract tool. It returns the rawS1_GATESarray and theS1_SCORESrubric anchors so the agent can render the gate definitions, the rubric anchors, or a "what would I be judged on" view before it commits a diff. No review runs; this is a metadata call.
A tool call is dispatched on the tools/call method:
if (method === "tools/call") {
const { name, arguments: args } = params || {};
if (name === "codeotter_review_diff") {
try {
const res = await runReview(args.diff, { title: args.title, body: args.body });
return send({
jsonrpc: "2.0", id,
result: { content: [{ type: "text", text: JSON.stringify(res, null, 2) }] },
});
} catch (err) {
return send({ jsonrpc: "2.0", id, error: { code: -32603, message: err.message } });
}
}
if (name === "codeotter_get_gates") {
return send({
jsonrpc: "2.0", id,
result: { content: [{ type: "text", text: JSON.stringify({ gates: S1_GATES, rubrics: S1_SCORES }, null, 2) }] },
});
}
}
Tool errors are surfaced as JSON-RPC -32603 (Internal Error) with the thrown message in error.message. Method-not-found is -32601. The dispatch loop is a flat if ladder; there is no router, no middleware, no plugin system.
What codeotter_review_diff actually invokes: the runReview payload
The agent's call to codeotter_review_diff is, byte-for-byte, the same code path as codeotter review on the CLI. That is the design point: the MCP tool is not a thin wrapper, it is the same runReview(diff, options) function the platform uses. Whatever the agent gets back is exactly what the platform review, the codeotter ci step, and the codeotter/triage commit status see.
The pipeline, in order:
- Parse the diff with
parseDiff(diffText)— extracts[{ path, additions, deletions }]per file. - Extract symbols with
extractSymbolsFromDiff(diff)— function, method, and class names in the changed lines. - Find outside impact with
findOutsideImpact(symbols, files)— usesgit grep -n -w <symbol>to count callers outside the diff. - Compute blast radius with
blastRadius(files, outsideCallers, outsideFiles)— the gauge lives incore/server.mjs, not in the CLI. It returns thescore(0–100) plusfiles,lines,dirs,hotspots,testFiles,outsideCallers,outsideFiles. - Build the review prompt with the diff facts, the outside-caller snippets, and the
AGENTS.md/CLAUDE.mdguidelines (if present) — see the team-rules deep-dive for howgetLocalGuidelines()works. - Call the language model with the prompt (provider resolved by
resolveModelConfig({title, body, diff, ...})). - Parse the JSON response and validate the scorecard shape.
- Run the self-check pass — a second pass of the same model scores each candidate finding 0–10 against the diff; findings below the configured minimum (default 5) are dropped. The score shows on each finding.
- Render and return the final payload.
The shape the agent sees is the same JSON the platform's POST /v1/systemone consumes:
{
"scores": {
"quality": 78,
"correctness_risk": 18,
"test_coverage": 70,
"readability": 84,
"pr_hygiene": 80
},
"gates": [
{ "id": "title", "label": "Title check", "pass": true, "explanation": "..." },
{ "id": "description", "label": "Description check", "pass": true, "explanation": "..." },
{ "id": "security", "label": "Security", "pass": true, "explanation": "..." },
{ "id": "complexity", "label": "Complexity", "pass": true, "explanation": "..." },
{ "id": "tests", "label": "Tests", "pass": true, "explanation": "..." },
{ "id": "docs", "label": "Documentation", "pass": false, "explanation": "PUBLIC API CHANGE — no CHANGELOG entry." },
{ "id": "scope", "label": "Scope", "pass": true, "explanation": "..." },
{ "id": "guidelines", "label": "Repository guidelines","pass": true, "explanation": "..." }
],
"summary": "Tightens user-signup email validation to require a TLD...",
"walkthrough": [
{ "file": "src/auth/validate.ts", "change": "Adds a TLD allowlist check in validateEmail..." },
{ "file": "src/auth/validate.test.ts", "change": "Adds 6 boundary tests for TLD allowlist..." }
],
"findings": [
{
"file": "src/auth/validate.ts",
"line": 42,
"severity": "suggestion",
"title": "Tighten IDN homograph check to Punycode-decode first",
"detail": "The current IDN guard checks raw Unicode. Punycode-decode first to catch Cyrillic-a / Latin-a substitutions.",
"confidence": 0.8,
"suggestion": "if (!email.match(/^[\\x21-\\x7e]+@([\\w-]+\\.)+[a-z]{2,}$/i)) throw new ValidationError('email.invalid');"
}
],
"blast": { "score": 42, "files": 2, "lines": 44, "dirs": 1, "hotspots": ["auth"], "testFiles": 1, "outsideCallers": 3, "outsideFiles": 2 },
"outsideImpact": { "outsideCallers": 3, "uniqueFiles": 2, "callers": [...] },
"model": "anthropic/claude-3-5-sonnet-latest"
}
The agent can use gates[] to decide whether to commit or hold, findings[].suggestion blocks to apply patches, and outsideImpact.callers[] to update callers it missed. The full rubric is the same S1_GATES and S1_SCORES the CLI-in-CI post and the dual-engine deep-dive document.
The server-side POST /v1/systemone adds one extra gate the MCP path does not see: the 9th, Issue Requirements, which validates the diff against a linked GitHub issue's acceptance criteria. That gate needs the forge API; the agent's local review is diff-only.
The self-check pass: how the loop's signal stays reliable
A language model will hallucinate findings. It will cite line numbers that do not exist, flag "deprecated APIs" that are not deprecated, and invent refactor suggestions that do not parse. CodeOtter's self-check is a second pass of the same model that verifies every candidate finding against the actual diff hunks and discards anything that fails the check.
The pass is wired into the review pipeline at the end. The mechanism: after the model returns the candidate findings, the CLI sends the same diff back to the same model with the candidate findings and asks for a per-finding 0–10 score. Findings whose score is below the configured minimum (default 5) are dropped. The score itself is preserved on the finding under confidence (a 0–1 normalized value), so the agent's tool runner can show "0.8 / 1.0" next to the ones that survived.
You are the CodeOtter self-check pass. For each candidate finding, score 0-10 how strongly the finding is grounded in the diff hunks below. GIT DIFF: \`\`\`diff <diff content> \`\`\` CANDIDATE FINDINGS: <JSON of candidate findings> Return ONLY valid JSON mapping each finding to an integer 0-10. Findings scoring below the configured minimum are dropped.
The honest trade-off: the self-check pass roughly doubles the wall-clock latency of a review. On a hosted model via BYOK, a typical 200-line diff review is a few seconds without the self-check and noticeably longer with it. On a local GGUF sidecar the self-check is the bottleneck of the local path; an agent that wants faster feedback should set the repository's Self-check to Off under Repository settings → Review. The MCP server inherits whatever the operator configured — there is no per-call override.
That is the right default for an agent-driven loop: the bottleneck of the loop should be the cost of a wrong suggestion, not the cost of a fast one.
Wiring it into Claude Code, Cursor, or Windsurf
Integration is one mcpServers.json entry. The agent spawns the CLI as a child process, holds it open for the session, and speaks JSON-RPC on its stdio.
Claude Code (~/.config/claude-code/mcp_servers.json or the per-project equivalent):
{
"mcpServers": {
"codeotter": {
"command": "node",
"args": ["/abs/path/to/tui/codeotter.mjs", "mcp"],
"env": {
"ANTHROPIC_API_KEY": "<byok-or-empty>"
}
}
}
}
Cursor (Settings → Models → Model Context Protocol → Add new MCP server, or ~/.cursor/mcp.json):
{
"mcpServers": {
"codeotter": {
"command": "node",
"args": ["/abs/path/to/tui/codeotter.mjs", "mcp"],
"env": { "ANTHROPIC_API_KEY": "<byok-or-empty>" }
}
}
}
Windsurf (~/.codeium/windsurf/mcp_config.json):
{
"mcpServers": {
"codeotter": {
"command": "node",
"args": ["/abs/path/to/tui/codeotter.mjs", "mcp"],
"env": { "ANTHROPIC_API_KEY": "<byok-or-empty>" }
}
}
}
The env block is for the model API key. The CLI's resolveProvider() walks the supported BYOK env vars first (ANTHROPIC_API_KEY for Claude, OPENAI_API_KEY for OpenAI, MINIMAX_API_KEY for MiniMax, OPENROUTER_API_KEY for OpenRouter); if none of those is set, it falls back to the ollama provider by default — an air-gapped box that runs a local Ollama sidecar on http://localhost:11434 needs no env at all and gets Ollama. The OLLAMA_HOST env var only customizes the sidecar's base URL; it is not a provider selector. To force Ollama when another BYOK env is also set, pass --provider ollama.
The agent then sees codeotter_review_diff and codeotter_get_gates in its tool list. A typical inner loop:
- Agent writes or edits code.
- Agent runs
git diff(orgit diff --cachedfor staged) to get the diff. - Agent calls
codeotter_review_diff({ diff, title: "<agent's commit message draft>", body: "<agent's PR description draft>" }). - Agent reads the JSON-RPC response:
content[0].textis the fullrunReviewpayload as a string. - Agent inspects
gates[]for anypass: falseitems. - If a gate failed, the agent either fixes the diff (calls
codeotter_review_diffagain on the new diff) or escalates to the human. - If all gates pass, the agent reads
findings[].suggestionblocks and applies them as patches (or holds them for the human). - Agent commits.
The MCP tool is not a one-shot gate — it is a negotiation surface. The agent can call it as many times as it wants, on any diff, and use the structured response to drive a self-correction loop. The self-check pass is the key: it makes the loop's signal reliable enough for an LLM agent to use as a hard gate.
The JSON-RPC content shape and what the agent parses
The MCP spec requires tool results to be an array of typed content blocks. CodeOtter's MCP server uses text blocks (the most common shape):
// request
{
"jsonrpc": "2.0", "id": 42,
"method": "tools/call",
"params": {
"name": "codeotter_review_diff",
"arguments": { "diff": "...", "title": "scope validateEmail to user-signup", "body": "Closes #42" }
}
}
// response
{
"jsonrpc": "2.0", "id": 42,
"result": {
"content": [
{
"type": "text",
"text": "{ \"scores\": { ... }, \"gates\": [ ... ], ... }"
}
]
}
}
The text field is a string containing the JSON-serialized runReview payload. The agent's tool runner parses text back to JSON before doing anything with it. This is the standard MCP text block shape; an agent that speaks MCP already knows how to deserialize it.
For codeotter_get_gates, the response is the same shape with text containing the S1_GATES array and the S1_SCORES rubric anchors:
{
"content": [
{
"type": "text",
"text": "{\n \"gates\": [\n { \"id\": \"title\", \"label\": \"Title check\", \"q\": \"...\", \"risk\": false },\n { \"id\": \"security\", \"label\": \"Security\", \"q\": \"...\", \"risk\": true },\n ...\n ],\n \"rubrics\": {\n \"quality\": [\"Broken or wrong\", \"Works but sloppy\", \"Acceptable\", \"Clean and idiomatic\", \"Exemplary\"],\n \"correctness_risk\": [\"No realistic way to break anything\", \"Low risk\", \"Moderate risk of regressions\", \"High risk of regressions\", \"Very likely to break production\"],\n \"test_coverage\": [\"No tests for the change\", \"Minimal tests\", \"Partial coverage\", \"Good coverage\", \"Thorough coverage\"],\n \"readability\": [\"Hard to follow\", \"Below average\", \"Readable\", \"Clear\", \"Very clear\"],\n \"pr_hygiene\": [\"Unclear title and description, mixed concerns\", \"Weak description or scope\", \"Adequate\", \"Well described and focused\", \"Exemplary title, description and scope\"],\n \"blast_radius\": [\"Isolated change with no downstream effect\", \"Small local impact\", \"Moderate impact on nearby modules\", \"Wide impact across several areas\", \"System-wide or critical-path impact\"]\n }\n}"
}
]
}
The S1_SCORES rubric anchors are the 0/25/50/75/100 strings the System 1 model uses to anchor its score. An agent that wants to render a "what would I be judged on" view for the human can call codeotter_get_gates once at session start and reuse the response.
Errors are surfaced as JSON-RPC errors. A review that throws (model unreachable, JSON parse failure, etc.) returns:
{ "jsonrpc": "2.0", "id": 42, "error": { "code": -32603, "message": "Cannot connect to model provider at http://localhost:11434" } }
The agent should treat tool errors as "review did not run" — the diff was not validated, so the agent should escalate to the human or retry with a different model. The MCP server does not return a partial review; it fails the whole call.
The team-rules bridge: AGENTS.md and CLAUDE.md
getLocalGuidelines(repoRoot) is called automatically by runReview and walks the repo root for AGENTS.md and CLAUDE.md. If either file is found, its contents are injected into both the review prompt and the self-check pass. The platform dashboard does the same on the server side via the forge API; the CLI does the same with a node:fs read at the repo root.
The bridge matters because the agent that writes the diff is not a generic engineer — it does not know the team's "always wrap errors with appErr()," "never use lodash.merge in the billing path," or "every new public API needs a CHANGELOG entry." Without the file injection, the agent's loop is bounded by a generic linter. With it, the loop is bounded by the same Guidelines gate a human reviewer would apply. The 1-click "Dismiss & remember rule" pattern (see the team-rules deep-dive) is the same UX on the platform dashboard for human reviewers; the MCP path inherits the rules automatically because runReview is the same function.
View Mermaid source
flowchart LR
A["AI coding agent<br/>(Claude Code / Cursor / Windsurf)"] -->|writes diff| D["git diff --cached"]
D -->|spawns child process| C["node tui/codeotter.mjs mcp<br/>(stdio JSON-RPC)"]
C -->|tools/call| R["runReview diff, options"]
R -->|reads| G["AGENTS.md / CLAUDE.md<br/>(getLocalGuidelines)"]
R -->|dispatch| P["resolveModelConfig<br/>(Anthropic / OpenAI / MiniMax / OpenRouter /<br/>Ollama)"]
P -->|first pass| L1["Language model<br/>candidate findings"]
L1 -->|second pass| L2["Self-check pass<br/>0-10 per finding"]
L2 -->|keeps ≥ 5| F["Final findings<br/>(with confidence)"]
R -->|also runs| S1["System 1<br/>6 S1_SCORES + 8 S1_GATES"]
S1 --> J["judge"]
F --> J
J -->|content: text| A
The diagram is the whole story. The agent is on the left, the MCP server is in the middle, the dual engines (System 1 deterministic, System 2 narrative + self-check) are on the right, and the JSON-RPC content: text response carries the verdict back.
What this changes for a team
For the AI coding agent running locally with codeotter mcp registered, the contract is one mcpServers.json entry. The agent then self-reviews every diff it is about to commit, gets a typed scorecard + gates + committable suggestions back, and applies them. The self-check pass is on. The AGENTS.md is enforced. The diff stays on the machine.
For the senior IC wiring the agent on a team of 20+, the value is AGENTS.md enforcement. The AGENTS.md is no longer aspirational — it is injected into the agent's review prompt and the self-check pass, and any finding that violates a guideline becomes a guidelines gate failure. The 1-click "Dismiss & remember rule" pattern is the same UX on the platform dashboard for human reviewers; the MCP path inherits the rules automatically.
For the security lead writing the audit story, the network story is the same as the offline-mode deep-dive: during an MCP-driven review the agent hands the diff to the codeotter_review_diff tool over stdio, and the review calls the engines you configured: the model provider you chose, or the sidecars and Ollama on 127.0.0.1. Any huggingface.co fetch for local models happened at admin time. The MCP server has no HTTP port and no daemon, and the MCP transport itself makes no network calls. The audit reads the CLI's outbound-call list (your model provider, or 127.0.0.1 for local models once the weights and runtimes are on disk), not the MCP spec. The separate codeotter pr command reads a pull request through gh, so that one also talks to your code host.
For the CFO comparing this to CodeRabbit or Greptile, the dollar math is the same as the rest of the platform: $0 forever on self-hosted infra vs CodeRabbit's entry plan at $24–$30/dev/month (annual vs monthly billing; pricing page checked 2026-10-31) or Greptile's usage-based $1-per-credit billing. The agent's review cost is electricity plus the model provider's per-token cost (zero for local Ollama). There is no per-agent tax, no per-review tax, no SaaS webhook.
Where this still loses, honestly
- MCP is stdio only. The server does not implement HTTP+SSE transport. That is deliberate — the only intended deployment is local IDE integration, and stdio is the canonical shape. An air-gapped box that wants a remote MCP server is out of scope (and out of the threat model).
- The agent must be running locally.
codeotter mcpis a local subprocess. A SaaS-hosted agent that wants to call it must be on the same machine as the CLI (or use a tunnel like Tailscale SSH). For a team that wants the agent in a sandboxed container, the CLI runs there. - The 9th gate (
Issue Requirements) is server-side only. The MCP tool runs the same 8S1_GATESas the CLI, not the server-sidegate_issue_requirementsthat requires a forge API. The agent's review cannot validate "Closes #42" against an issue body — that gate is the platform's job (see the CLI-in-CI post for the 9-vs-8 split). - The self-check doubles the wall-clock latency of a review. There is no per-call override on the MCP tool. Operators who want a faster inner loop should set the repository's
Self-checktoOffunderRepository settings → Review. - AGPL-3.0 is OSI-OSS but copyleft. The CLI ships under the GNU Affero General Public License v3.0 (AGPL-3.0). Free to self-host, modify, and redistribute; a modified version offered as a network service must publish its source. The MCP server inherits the same license. You own the binary; if you offer it as a service, you owe the changes back.
Where to go next
- Walk the wire-level contract for
codeotter ciin the CLI-in-CI blog — sameS1_GATES, sameS1_SCORES, same JSON shape, but with the--fail-on-gateexit-code contract and the two-tiercodeotter/triage+codeotter cipipeline. - The
runReviewpayload shape is documented in the dual-engine deep-dive — same JSON the platform'sPOST /v1/systemoneconsumes. - The team-rules injection (
AGENTS.md/CLAUDE.mdauto-detection, the 1-click "Dismiss & remember rule" team-learning loop) is in the AGENTS.md-as-merge-gate blog. - The incremental delta review (
prevSha → headSha) is in the incremental-delta engineering blog. - The local-model roster (open-weight GGUF sidecars, the offline path) is in the offline-mode deep-dive.
- The CLI source —
tui/codeotter.mjs,mcpsubcommand at the bottom of the file,startMcpServer()andgetLocalGuidelines()exported — is at github.com/dharmeshgurnani/CodeOtter/blob/main/tui/codeotter.mjs. - The Model Context Protocol spec (the version this build speaks) is at modelcontextprotocol.io/specification/2024-11-05.
If you want an AI coding agent that self-reviews before git commit, install the CLI, add one mcpServers.json entry, and let the agent call codeotter_review_diff on its own diffs. The self-check pass is on. The AGENTS.md is enforced. The diff stays on the machine.
CodeOtter ships under the GNU Affero General Public License v3.0 (AGPL-3.0) — free to self-host, modify, and redistribute; a modified version offered as a network service must publish its source. The codeotter mcp subcommand speaks Model Context Protocol 2024-11-05 on stdio, registers two tools (codeotter_review_diff, codeotter_get_gates), and runs the same dual-engine System 1 + System 2 pipeline that runs in the platform and in CI. The AI agent that writes the code is the same agent that calls the gate.


