Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Hedgehog Create a spike to evaluate migrating our database from Postgres to DynamoDB."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for structured spike investigations and Architecture Decision Record (ADR) generation.
Manages technical spike investigations with:
Enforced 4-phase workflow: Meta-design → Divergent exploration → Adversarial challenge → Synthesis
State machine: Prevents skipping phases or invalid transitions
Checkpoint/rollback: Save and restore investigation state
ADR generation: Auto-generates ADRs from exploration artifacts
Dead-end tracking: Documents abandoned approaches for future reference
Related MCP server: Gravitas-Core-MCP
git clone https://github.com/jpalmerr/Hedgehog.git
cd Hedgehog
pip install .Then add to your Claude Code MCP settings (~/.claude.json):
{
"mcpServers": {
"hedgehog": {
"command": "hedgehog",
"args": []
}
}
}Or via the CLI:
claude mcp add hedgehog --scope user -- hedgehogHere's how a real investigation looks in Claude Code. You talk to Claude naturally — Hedgehog manages the structure behind the scenes.
You: I need to investigate options for migrating our Kafka topic IDs from numeric to string-based. Create a spike for this.
Claude calls spike_create("kafka-topic-migration", "Evaluate approaches for migrating Kafka topic IDs from numeric to string-based identifiers") and generates a meta-design template covering the problem statement, key questions, success criteria, and constraints.
You: The meta-design looks good. The key constraint is zero downtime — we can't stop consumers during migration. Approve it and let's start exploring.
Claude calls spike_approve_meta → advances to Phase 1. State is checkpointed automatically.
You: Let's explore three approaches: dual-write, shadow topics, and a proxy translation layer.
Claude registers all three branches and starts investigating the first one — reading docs, considering trade-offs, and documenting findings for each branch as it goes.
You: Pick up the kafka-topic-migration spike. Where did we leave off?
Claude calls spike_get_state → sees Phase 1 with one branch explored, two remaining. Continues investigating the remaining branches.
When the third branch is completed, Hedgehog automatically advances to Phase 2 (adversarial challenge) and checkpoints the state.
You: Continue the spike. Challenge each approach — focus on failure modes and hidden assumptions.
Claude systematically challenges each branch: What happens during a dual-write if one write fails? What's the rollback story for shadow topics? How does the proxy handle schema evolution?
When all branches are challenged, Hedgehog auto-advances to Phase 3. Claude synthesizes the findings, generates an ADR with the recommendation, and you approve it.
Throughout this flow, Claude is calling Hedgehog tools:
spike_create / spike_approve_meta → Phase 0 (framing)
spike_add_branch / spike_complete_branch → Phase 1 (exploration)
spike_add_challenge → Phase 2 (adversarial)
spike_synthesize / spike_generate_adr → Phase 3 (synthesis)
spike_approve_adr → CompleteCheckpoints are created automatically at each phase transition. Use spike_checkpoint for manual saves and spike_rollback to revert if an exploration path goes nowhere.
A full spike investigation is a significant piece of work — comparable to a multi-day task you'd do at work. Hedgehog persists all state to disk (~/.claude/spikes/), so you can spread an investigation across as many Claude Code sessions as you need.
Natural session boundaries:
Session 1: Frame the problem (Phase 0), start exploration
Session 2-3: Complete branch explorations (Phase 1)
Session 4: Adversarial challenges + synthesis (Phases 2-3)
Use spike_get_state at the start of any session to pick up where you left off.
Not every technical question needs a full spike. Use Hedgehog when:
The decision is hard to reverse (infrastructure, data model, core architecture)
There are genuinely 3+ viable approaches worth comparing
You need a defensible ADR for your team
For smaller questions, just ask Claude directly — no ceremony needed.
Hedgehog's own overhead is minimal (small JSON tool calls). The tokens go on Claude thinking about your problem — reading code, researching approaches, writing analysis. A full 3-branch investigation is token-intensive because the work is intensive.
On a Pro plan, lean into the multi-session workflow. Do one branch per session if needed. The checkpoint system means you never lose progress.
Define the investigation scope, key questions, and success criteria. Forces you to think about whether you're solving the right problem.
Explore at least 3 distinct approaches. Don't converge prematurely—document advantages, disadvantages, and open questions for each.
For each branch, systematically identify failure modes, challenge assumptions, and find second-order effects.
Compare branches, produce a recommendation with uncertainty bounds, and generate an ADR documenting the decision.
Tool | Description |
| Create new spike investigation |
| List all spikes |
| Get current spike state |
| Approve meta-design, advance to Phase 1 |
| Register a branch for exploration |
| Mark branch as explored with findings |
| Document abandoned approach |
| Add adversarial challenge to branch |
| Create synthesis document |
| Generate ADR from artifacts |
| Mark spike complete |
| Save current state |
| Restore to checkpoint |
| Archive completed spike |
| Delete spike |
URI | Description |
| Current spike state as JSON |
| Meta-design document |
| List of branch documents |
| Specific branch content |
| Challenge document for branch |
| Generated ADR |
# Clone and setup
git clone https://github.com/jpalmerr/Hedgehog
cd Hedgehog
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
# Run tests
pytest
# Type check
mypy src
# Lint
ruff check src testsMIT
Register a new exploration branch for a spike.
Branches represent distinct approaches to solving the problem. Can be added during Phase 0 (planning) or Phase 1 (divergent).
Args: name: Spike name branch_name: Filesystem-safe branch name description: What this branch explores
Inputs: name (required), branch_name (required), description (required). Returns: result
Add adversarial challenge to a branch.
Challenges document failure modes, hidden assumptions, and edge cases. When all explored branches are challenged, the spike automatically advances to Phase 3 (synthesis).
Args: name: Spike name branch_name: Branch to challenge (must be in EXPLORED status) challenge_md: Markdown content with adversarial challenge
Inputs: name (required), branch_name (required), challenge_md (required). Returns: result
Approve the ADR and mark the spike as completed.
This is the final gate. The spike transitions to COMPLETED status.
Args: name: Spike name
Inputs: name (required). Returns: result
Approve meta-design and advance spike from Phase 0 to Phase 1.
This is a gate: the spike cannot proceed to divergent exploration until the problem framing is approved.
Args: name: Spike name
Inputs: name (required). Returns: result
Archive a spike investigation (move to archive directory).
Args: name: Spike name to archive
Inputs: name (required). Returns: result
Create a checkpoint of the current spike state.
Checkpoints allow rolling back to a previous state if exploration goes down an unproductive path.
Args: name: Spike name label: Human-readable checkpoint label
Inputs: name (required), label (required). Returns: result
Mark a branch as explored and record findings.
The findings markdown replaces the branch template content. When enough branches are explored (>=3), the spike automatically advances to Phase 2 (adversarial).
Args: name: Spike name branch_name: Branch to mark as explored findings_md: Markdown content with exploration findings
Inputs: name (required), branch_name (required), findings_md (required). Returns: result
Create a new spike investigation.
Initializes a spike with a problem statement, creates the directory structure, and generates the meta-design template for Phase 0.
Args: name: Filesystem-safe name (alphanumeric, hyphens, underscores, max 64 chars) problem_statement: The problem this spike investigates
Inputs: name (required), problem_statement (required). Returns: result
Permanently delete a spike investigation.
Args: name: Spike name to delete confirm: Must be True to confirm deletion
Inputs: name (required), confirm (required). Returns: result
Generate an Architecture Decision Record from spike artifacts.
Builds alternatives from challenged branches and renders the ADR template.
Args: name: Spike name title: ADR title context_text: Context/background for the decision decision: The decision being documented
Inputs: name (required), title (required), context_text (required), decision (required). Returns: result
Get the current state of a spike investigation.
Args: name: Spike name
Inputs: name (required). Returns: result
List all spike investigations with summary information.
Inputs: no named parameters. Returns: result
Mark a branch as a dead end and document why.
Dead-end branches are excluded from synthesis but their documentation is preserved for future reference.
Args: name: Spike name branch_name: Branch to mark as dead end reason: Why this branch was abandoned salvageable: Any insights salvageable from this branch
Inputs: name (required), branch_name (required), reason (required), salvageable. Returns: result
Rollback spike to a previous checkpoint.
Restores the full state from the checkpoint snapshot.
Args: name: Spike name checkpoint_id: Checkpoint ID to restore from
Inputs: name (required), checkpoint_id (required). Returns: result
Create synthesis document comparing all explored branches.
Args: name: Spike name synthesis_md: Markdown content with synthesis analysis
Inputs: name (required), synthesis_md (required). Returns: result
Record a confidence rating for the spike.
All ratings are 0-100. Tracks confidence evolution over time.
Args: name: Spike name problem_understanding: How well is the problem understood (0-100) success_criteria_clarity: How clear are the success criteria (0-100) exploration_completeness: How complete is the exploration (0-100) solving_right_problem: Confidence we're solving the right problem (0-100) reason: Optional reason for this assessment
Inputs: name (required), problem_understanding (required), success_criteria_clarity (required), exploration_completeness (require… Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 16 tools
Every tool has a clearly distinct purpose within the spike investigation lifecycle. The tools cover different phases (planning, exploration, synthesis, completion) and specific actions (create, add branch, challenge, checkpoint, rollback, etc.) with no overlap or ambiguity. An agent can easily distinguish between tools like spike_add_branch, spike_complete_branch, and spike_mark_dead_end based on their distinct roles.
All tools follow a perfect 'spike_verb_noun' naming pattern throughout. The verb-noun structure is consistent (e.g., spike_create, spike_add_branch, spike_generate_adr), using snake_case uniformly. This predictable naming makes it easy for agents to understand and navigate the toolset.
With 16 tools, the count is slightly high but reasonable for the comprehensive spike investigation domain. It covers the full lifecycle from creation to archival, including branching, challenges, checkpoints, and synthesis. While it might feel heavy, each tool appears to earn its place for a specific workflow step.
The toolset provides complete coverage of the spike investigation domain, supporting all phases from planning (create, approve meta) through exploration (add branch, complete branch, mark dead end) to synthesis (generate adr, synthesize) and completion (approve adr, archive). There are no obvious gaps; agents can manage the entire lifecycle without dead ends.
MCP server for building and testing AI agents with multi-model experimentation and insights.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol (MCP) application for automated GitHub PR analysis and issue management.…
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server