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

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

Tools

deep_scan — Initial Reconnaissance

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

deep_explore — Recursive What-If Analysis

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

deep_synthesize — Final Report

Produces a prioritized action plan from the completed reasoning tree.

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

deep_list_sessions — List Saved Sessions

deep_resume — Resume a Session

deep_save_session — Save Manually

deep_delete_session — Delete a Session

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

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 — [email protected]

License

MIT