Getting Started

Get DeepPlan MCP running in your IDE in under 5 minutes.

What is DeepPlan?

DeepPlan is a Model Context Protocol (MCP) server that upgrades shallow architecture plans into production-ready blueprints. Instead of relying on a single AI response, DeepPlan runs a Council of Architects — multiple specialized AI personas that analyze your plan from different angles (security, performance, UX, DevOps, etc.) then a Chair persona synthesizes everything into a unified, actionable blueprint.

Why use DeepPlan over a regular AI prompt?

• Multi-perspective analysis — 4+ expert personas catch issues a single prompt would miss
• Custom councils — build your own expert teams for different project types (e-commerce, IoT, SaaS, etc.)
• Strategy, not code — returns architecture decisions, edge cases, and ordered next steps — not boilerplate code
• IDE-native — works inside Windsurf, Cursor, and VS Code via MCP protocol

The AI Engines

DeepPlan uses two proprietary AI engines optimized for different stages of analysis:

System Requirements

Installation

Option A: npx (no install — recommended)

Use npx deepplan-mcp directly in your MCP config — npm will download and run it automatically. No global install needed.

Option B: npm global install

npm install -g deepplan-mcp

Option C: From source

git clone https://github.com/nicepkg/deepplan.git
cd deepplan/client
npm install
npm run build

Add to Your IDE

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "deepplan": {
      "command": "npx",
      "args": ["-y", "deepplan-mcp"],
      "env": {
        "DEEPPLAN_API_KEY": "dpk_your-key-here"
      }
    }
  }
}

After saving, restart Windsurf or reload the MCP servers from the MCP panel.

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "deepplan": {
      "command": "npx",
      "args": ["-y", "deepplan-mcp"],
      "env": {
        "DEEPPLAN_API_KEY": "dpk_your-key-here"
      }
    }
  }
}

After saving, restart Cursor or use the command palette → “MCP: Reload Servers”.

VS Code

Add to your workspace .vscode/mcp.json:

{
  "servers": {
    "deepplan": {
      "command": "npx",
      "args": ["-y", "deepplan-mcp"],
      "env": {
        "DEEPPLAN_API_KEY": "dpk_your-key-here"
      }
    }
  }
}

Note: VS Code requires the MCP extension to be installed. The config format differs slightly from Windsurf/Cursor.

Claude Code

Add DeepPlan as an MCP server with the CLI:

claude mcp add deepplan -- npx -y deepplan-mcp

Then set your API key as an environment variable:

export DEEPPLAN_API_KEY="dpk_your-key-here"

Or add to your project’s .mcp.json:

{
  "mcpServers": {
    "deepplan": {
      "command": "npx",
      "args": ["-y", "deepplan-mcp"],
      "env": {
        "DEEPPLAN_API_KEY": "dpk_your-key-here"
      }
    }
  }
}

Usage example:

claude> use deepplan to upgrade my architecture plan for a SaaS with auth and payments

Claude Code will automatically call upgrade_architecture_blueprint and return a production-ready blueprint.

Your First Plan

Ask your IDE AI agent to upgrade a plan:

“I want to build a real-time chat app with SvelteKit and Cloudflare. Use the DeepPlan MCP to upgrade this plan.”

The agent will call upgrade_architecture_blueprint and receive a production-ready blueprint with:

• Architecture Directives — specific decisions with reasoning
• Edge Cases & Failure Modes — issues you didn’t think of
• Required Constraints — non-negotiable security/performance requirements
• Recommended Patterns — design patterns for your tech stack
• Next Steps for Agent — numbered, ordered steps the AI can execute immediately

How It Works

1. IDE + AI sends your draft plan to DeepPlan MCP
2. DeepPlan Scout auto-selects the best deployed council based on your plan content and persona expertise
3. Expert personas (non-chair) analyze the plan in parallel — each from their specialty using DeepPlan Scout engine
4. Chair persona synthesizes all expert reports into a unified blueprint using DeepPlan Architect engine
5. Blueprint is returned to your IDE for the AI agent to execute

Troubleshooting

“DEEPPLAN_API_KEY is not set”

Make sure your API key is correctly set in your IDE’s MCP config file. The key should start with dpk_.

“MCP server not found”

Verify that npx deepplan-mcp runs correctly from your terminal. If it fails, check your Node.js version (node --version should be 18+).

“Rate limit exceeded”

Free tier allows limited calls per hour. Purchase credits from the Pricing page for higher limits.

Blueprint quality seems low

• Be specific — “real-time chat with rooms and file sharing” is better than “an app”
• Always include tech_stack — enables stack-specific recommendations
• Add constraints — “must run on Edge Runtime” prevents incompatible suggestions
• Deploy your councils — only deployed councils (green dot) are available for MCP

Next Steps

• Configuration — Customize engines, API keys, and modes
• Usage Examples — Real-world planning scenarios and tips