Deep Reasoning MCP Server

A Model Context Protocol server that turns Claude Code into a recursive analysis engine. Instead of linear reasoning, it builds explorable decision trees where every finding is traced as an IF/THEN chain, challenged with mitigations, and expanded into sub-findings at configurable depth.

Why

Claude Code is excellent at reasoning, but complex problems — architecture reviews, production debugging, incident triage — benefit from structured exploration. Without structure, analysis tends to be shallow: the first plausible explanation wins, edge cases are missed, and mitigations are proposed without examining the risks they introduce.

Deep Reasoning forces a disciplined process:

1. Scan — Map the problem space, identify 3-7 critical areas
2. Explore — For each finding, trace the full consequence chain. Challenge every mitigation: "Does this fix introduce new problems?" Discover sub-findings.
3. Synthesize — Produce a prioritized action plan, residual risks, and decision log

The result is an analysis that is reproducible, auditable, and significantly more thorough than a single-pass review.

How It Works

                    deep_scan             Initial reconnaissance
                        |                Identifies 3-7 key findings
                        v                May ask clarifying questions
                   deep_explore          Recursive what-if chains
                  /     |     \          Loops until max depth
             Branch  Branch  Branch      Each gets mitigations + sub-findings
                  \     |     /
                        v
                  deep_synthesize        Action plan, residual risks,
                                         decision log, quick wins

Sessions are persisted automatically. You can pause an analysis, close Claude Code, and resume days later with deep_resume.

Execution Modes

Mode	Cost	Requires	Best for
orchestrator	Zero extra	Any Claude Code plan	Interactive analysis where Claude Code reasons through the prompts itself
autonomous	API credits	ANTHROPIC_API_KEY	Batch analysis, CI/CD pipelines, non-Claude MCP clients

Auto-detection: if ANTHROPIC_API_KEY is set, defaults to autonomous. Otherwise, defaults to orchestrator. You can override per-call with the mode parameter.

Installation

From PyPI

pip install deep-reasoning-mcp

From source

git clone https://github.com/yourusername/deep-reasoning-mcp.git
cd deep-reasoning-mcp
uv sync

Configuration

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "deep-reasoning": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/deep-reasoning-mcp",
        "run",
        "deep-reasoning-mcp"
      ]
    }
  }
}

If installed from PyPI:

{
  "mcpServers": {
    "deep-reasoning": {
      "command": "deep-reasoning-mcp"
    }
  }
}

With autonomous mode

{
  "mcpServers": {
    "deep-reasoning": {
      "command": "deep-reasoning-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Environment Variables

Variable	Default	Description
ANTHROPIC_API_KEY	(none)	Enables autonomous mode. Not needed for orchestrator.
DEEP_REASONING_MODEL	claude-opus-4-20250514	Model for autonomous API calls
DEEP_REASONING_MAX_TOKENS	4096	Max tokens per autonomous API call
DEEP_REASONING_MAX_CONCURRENT	3	Max concurrent API calls (autonomous)
DEEP_REASONING_COOLDOWN_MS	500	Minimum delay between API calls in ms (autonomous)

Tools

deep_scan — Initial Reconnaissance

Always call this first. Maps the problem space and identifies critical findings.

Parameter	Required	Description
description	Yes	The problem, code, or architecture to analyze
analysis_type	No	architecture, code_review, debugging, incident, brainstorming (default: architecture)
context	No	Additional codebase/stack context
depth	No	Max exploration depth 1-5 (default: 3)
language	No	Output language code, e.g. en, it, de (default: en)
mode	No	orchestrator or autonomous (auto-detected)
model	No	Model override for autonomous mode

deep_explore — Recursive What-If Analysis

Explores specific branches of the reasoning tree. Call multiple times to deepen.

Parameter	Required	Description
tree	Yes	Reasoning tree JSON from deep_scan or previous deep_explore
branch_ids	No	Specific finding IDs to explore (default: all pending)
clarification_answers	No	Answers to pending questions {question_id: answer}
go_ahead	No	Skip unanswered clarifications and proceed (default: false)
mode	No	orchestrator or autonomous (auto-detected)
model	No	Model override for autonomous mode

deep_synthesize — Final Report

Produces a prioritized action plan from the completed reasoning tree.

Parameter	Required	Description
tree	Yes	Completed reasoning tree JSON
language	No	Report language (default: en)
mode	No	orchestrator or autonomous (auto-detected)
model	No	Model override for autonomous mode

Returns a Markdown report with: Executive Summary, Critical Findings, Action Plan, Quick Wins, Residual Risks, Decision Log.

deep_list_sessions — List Saved Sessions

Parameter	Required	Description
analysis_type	No	Filter by type
status	No	Filter by status (pending, exploring, complete)
limit	No	Max results 1-500 (default: 50)

deep_resume — Resume a Session

Parameter	Required	Description
session_id	Yes	Session ID (supports partial matching)

deep_save_session — Save Manually

Parameter	Required	Description
tree	Yes	Reasoning tree to save
session_name	No	Custom name (auto-generated if omitted)

deep_delete_session — Delete a Session

Parameter	Required	Description
session_id	Yes	Session ID to delete (exact match)

Usage Examples

Architecture review

Analyze the payment callback flow for race conditions.
Stack: Django 4.2, PostgreSQL, Celery, RabbitMQ.
PSPs send HTTP POST callbacks that can arrive within milliseconds of each other.

Production debugging

Payment callbacks timeout randomly after 30s under load.
Logs show the PSP responds in 2s. The issue started after last Thursday's deploy.
Stack: Django, Gunicorn (4 workers), PostgreSQL, Redis cache.

Incident triage

Production: ticket validation failing for operator CTM for ~20 minutes.
No recent deploys. Health checks pass. Grafana shows normal latency
but elevated 500s on the /api/v2/validate/ endpoint.

Brainstorming

We're evaluating migrating from Celery to Django-Q2 for async tasks.
We have ~50 Celery tasks, some with complex retry logic, beat scheduling,
and chain/chord patterns. What are the trade-offs?

Session Persistence

Sessions are saved automatically to ~/.claude/deep-reasoning/sessions/. Each session is a self-contained JSON file that captures the full reasoning tree.

~/.claude/deep-reasoning/
  sessions/
    20250409_152030_debugging_payment_callback.json
    20250408_091500_architecture_auth_flow.json
  index.json

Workflow:

1. Start: deep_scan(...) — session auto-saved
2. Pause: close Claude Code anytime
3. Resume: deep_list_sessions() then deep_resume({session_id: "payment_callback"})
4. Complete: deep_synthesize(...) — final report

Reasoning Tree Structure

The JSON tree passed between tools:

{
  "id": "a1b2c3d4",
  "version": "2.0",
  "analysis_type": "architecture",
  "max_depth": 3,
  "current_depth": 2,
  "status": "exploring",
  "language": "en",
  "description": "Original problem description",
  "findings": [
    {
      "id": "e5f6g7h8",
      "depth": 1,
      "status": "complete",
      "title": "Race condition on payment callback",
      "severity": "critical",
      "condition": "IF two callbacks arrive within 50ms for same transaction",
      "consequence": "THEN duplicate transaction record created",
      "mitigations": [
        {
          "action": "Add SELECT FOR UPDATE on transaction lookup",
          "where": "PaymentCallbackView.process_callback()",
          "risk_introduced": "Increased lock contention under high load",
          "effort": "medium"
        }
      ],
      "sub_findings": [
        {
          "id": "i9j0k1l2",
          "depth": 2,
          "status": "pending",
          "title": "Lock contention under peak load",
          "severity": "high",
          "condition": "IF >100 concurrent callbacks hit the same lock",
          "consequence": "THEN connection pool exhaustion, cascading timeouts"
        }
      ]
    }
  ],
  "metadata": {
    "total_findings": 5,
    "explored_findings": 3,
    "critical_count": 1,
    "high_count": 2
  }
}

Comparison with sequential-thinking

	sequential-thinking	deep-reasoning
Structure	Linear chain	Recursive tree
Depth	Single pass	Configurable 1-5 levels
Persistence	None	Auto-saved sessions
Best for	Quick orientation, simple problems	Thorough analysis, complex systems
Output	Thought stream	Structured report with action plan

They complement each other: sequential-thinking identifies the area, deep-reasoning explores it.

Project Structure

deep_reasoning_mcp/
  __init__.py      # Package entry point
  server.py        # MCP tool handlers
  models.py        # Pydantic models and enums
  tree.py          # Reasoning tree helpers
  session.py       # Session persistence
  prompts.py       # Analysis-type-specific prompts
  llm.py           # Anthropic API client with rate limiting

Author

Maurizio Mocci — mauriziomocci@gmail.com

License

MIT