Overthink

What is this?

Overthink is a Model Context Protocol (MCP) server that adds real engineering discipline to AI coding agents.

It is not another LLM.
It is a control layer that forces the agent to:

• Triage first

• Investigate with evidence

• Take one useful action at a time

• Avoid loops and side-paths

• Verify before claiming success

• Finish on time

It works with any MCP-compatible client, but it is purpose-built for Heinrich AI.

What is Heinrich AI?

Heinrich AI is a VS Code / Cursor extension that turns AI coding agents into disciplined engineers.
The Heinrich logo represents the product — a focused, no-nonsense AI coding companion that prioritizes finishing real work over endless reasoning.

Overthink is the intelligence backend that powers Heinrich’s strict workflow.

Stay tuned with Heinrich AI →
 Follow Heinrich AI on LinkedIn

Related MCP server: Task Agent MCP

Why Overthink?

Even the strongest models still fail at process:

How to connect Overthink MCP to Heinrich AI

1. Install & build Overthink

git clone https://github.com/missarii/overthink.git
cd overthink
npm install
npm run build

2. Get the absolute path to the server

After building, the entry point is:

/absolute/path/to/overthink/dist/index.js

Example (macOS / Linux):

echo "$(pwd)/dist/index.js"

3. Configure Heinrich AI / VS Code / Cursor

Open your MCP settings (Heinrich AI settings, or Cursor/VS Code MCP config) and add:

{
  "mcpServers": {
    "overthink": {
      "command": "node",
      "args": ["/absolute/path/to/overthink/dist/index.js"]
    }
  }
}

Replace /absolute/path/to/overthink/dist/index.js with the real path from step 2.

4. Restart the client

Restart Heinrich AI / Cursor / VS Code so it picks up the new MCP server.

5. Verify it is connected

In the agent chat you should see the Overthink tools available:

• overthink_start

• overthink_guard

• overthink_next_action

• overthink_check_progress

• overthink_verify

• overthink_finish

• …and the rest

Heinrich AI will automatically prefer the forced workflow defined in the heinrich-rules resource.

Alternative: HTTP mode

If you prefer HTTP transport:

npm run start:http
# → http://127.0.0.1:3921/mcp
# Health check: http://127.0.0.1:3921/health

Then configure the client to use the HTTP endpoint (if the client supports Streamable HTTP).

Architecture

AI Coding Agent (Heinrich AI / Cursor / Claude Code / …)
        ↓
┌─────────────────────────────────────────────────────────┐
│                   OVERTHINK MCP SERVER                  │
│                                                         │
│  • Fast Triage          • Action Guard                  │
│  • Reasoning Engine     • Investigation Engine          │
│  • Planning Engine      • Diagnosis Engine              │
│  • Execution Engine     • Verification Engine           │
│  • Progress Tracker     • Budget Controller             │
└─────────────────────────────────────────────────────────┘
        ↓
Evidence-backed result · Minimal changes · Short report

MCP Tools (full list)

Resources (rules injected into the agent)

Reasoning levels

Fast triage & budgets

On every overthink_start the server runs fast triage to detect the failure class (asset path, UI/copy/style, logic error, etc.) and applies a time box.

Default budgets (editable in policies/default.yaml):

Simple UI/asset tasks are automatically tightened further.

Action Guard — what gets blocked

The guard actively prevents common time-wasters:

• sleep N

• Drive-by package installs (npm install, pip install, …)

• Heavy browser automation just to check a simple UI issue

• Unbounded find / or deep whole-repo searches

• Running the entire test suite before a focused check

• Infra commands (Docker, kubectl, Terraform) unless the task is actually infra

• Redesign / rewrite / migrate on pure UI or image tasks

Near-duplicate actions are also blocked to kill fail-loops.

Example workflow

User: POST /api/auth/login returns HTTP 500

1. overthink_start
   → complexity: normal · level: L1 · time_box applied · hard limits set

2. overthink_next_action
   → single primary action (inspect auth route + recent error)

3. overthink_guard          ← before any risky shell command

4. overthink_investigate / overthink_diagnose
   → targeted evidence + ranked hypotheses

5. overthink_check_progress  ← after every step
   → detects similar/fail_loop → can force_stop

6. Apply minimal fix

7. overthink_verify          ← only real test/build results

8. overthink_finish
   → short verified report

Configuration

Policies live in policies/ (YAML):

Edit these files to change behaviour.

Project structure

overthink/
├── heinrich-logo.png            # Heinrich AI official logo
├── src/
│   ├── overthink-logo.png       # Overthink official logo
│   ├── index.ts                 # Entrypoint (stdio / HTTP)
│   ├── server.ts                # MCP server + tools + resources
│   ├── core/                    # Task manager, triage, guard, budgets…
│   ├── engines/                 # Reasoning, investigation, diagnosis…
│   ├── tools/                   # MCP tool implementations
│   ├── resources/
│   │   ├── core-policy.txt
│   │   └── heinrich-rules.txt
│   └── types/
├── policies/
│   ├── default.yaml
│   ├── coding.yaml
│   └── debugging.yaml
├── package.json
└── README.md

Safety guarantees

• Never auto-deletes user data

• Never claims success without evidence

• Respects workspace boundaries

• No silent dependency or config changes

• Explicit tool permissions via MCP

• Hard blocks on wasteful and off-path actions

License

MIT © 2026 missarii