Configuration

DeepPlan MCP is configured via environment variables in your IDE’s MCP config, a .env file, or CLI arguments.

Operation Modes

DeepPlan MCP supports two modes:

Proxy Mode (recommended)

Uses your DeepPlan API Key to call the DeepPlan backend. The backend handles AI engine routing, credit billing, council selection, and persona management.

{
  "env": {
    "DEEPPLAN_API_KEY": "dpk_your-key-here"
  }
}

Benefits:

Uses your custom councils and personas from the dashboard
AI engine routing is handled automatically — DeepPlan Scout for expert analysis, DeepPlan Architect for Chair synthesis
Tracks usage and credits
No additional API keys needed

Auto Mode: Configure in Settings → Auto Mode. When ON (default), DeepPlan Scout auto-selects the best deployed council for each plan. When OFF, it uses your Default Council directly.

Direct Mode (fallback)

Calls AI providers directly using 4 hardcoded expert personas (Security, Performance, UX/DX, DevOps). No custom councils or personas.

{
  "env": {
    "OPENROUTER_API_KEY": "sk-or-v1-your-key-here"
  }
}

When to use: Testing, local development, or when you don’t have a DeepPlan account.

If both keys are set, Proxy Mode takes priority.

Environment Variables

Variable	Default	Description
`DEEPPLAN_API_KEY`	—	Your DeepPlan API key (enables Proxy Mode)
`DEEPPLAN_API_URL`	`https://deepplan-website.pages.dev/api/mcp/council`	Custom API endpoint (advanced)
`OPENROUTER_API_KEY`	—	AI provider key (enables Direct Mode)
`COUNCIL_MODEL`	DeepPlan Scout engine	Model for expert persona analysis (Direct Mode only)
`LEAD_ARCHITECT_MODEL`	DeepPlan Architect engine	Model for Chair synthesis (Direct Mode only)
`DRAFT_PLAN_MAX_LENGTH`	`8000`	Maximum characters for input draft plan

CLI Arguments

You can also pass arguments directly:

{
  "command": "npx",
  "args": ["-y", "deepplan-mcp", "--api-key=dpk_your-key-here"]
}

Argument	Description
`--api-key=xxx`	Same as `DEEPPLAN_API_KEY`
`--api-url=xxx`	Same as `DEEPPLAN_API_URL`

AI Engines

DeepPlan Scout (Expert Analysis)

Used for parallel expert analysis and council auto-selection. Optimized for fast, cost-effective multi-persona evaluation with strong architectural reasoning.

In Proxy Mode, Scout is configured automatically. In Direct Mode, set COUNCIL_MODEL to override.

DeepPlan Architect (Chair Synthesis)

Used for the Chair persona’s final synthesis. Optimized for deep reasoning, conflict resolution between expert reports, and generating cohesive blueprints.

In Proxy Mode, Architect is configured automatically. In Direct Mode, set LEAD_ARCHITECT_MODEL to override.

Token Budget per Call

Each MCP call consumes tokens across multiple AI invocations:

Phase	Engine	Max Tokens	Purpose
AI Search	Librarian	—	Vectorize cache + Tavily web search
AI+IDE Enrichment	DeepPlan Architect	4,096	Enrich draft with search context
Auto-select	DeepPlan Scout	128–256	Pick the best experts/council
Expert × N (PRO)	DeepPlan Scout	1,024 each	Parallel persona analysis
Expert × N (CON)	DeepPlan Scout	1,024 each	Paired debate only
Chair synthesis	DeepPlan Architect	8,192	Unified blueprint output
AI+IDE Refinement	DeepPlan Architect	8,192	Final actionable plan

A typical Auto Council call with 4 experts uses approximately 25,000 tokens total. Paired Debate doubles the expert tokens. This is managed automatically — you only pay 1 credit per call regardless of token usage.

MCP Tools

`upgrade_architecture_blueprint`

The main tool. Sends a plan to the Council of Architects for expert review.

Parameter	Required	Description
`draft_plan`	Yes	Your architecture plan text (primary selection criteria)
`tech_stack`	No	e.g. “SvelteKit, Cloudflare Workers, D1” (supplementary context)
`model_choice`	No	Override the Chair synthesis engine for this call
`context_constraints`	No	e.g. “Must run on Edge Runtime” (supplementary context)

Note: draft_plan is the primary input that determines which council is auto-selected. tech_stack and context_constraints are supplementary — they’re passed to the experts but do NOT affect council selection.

`auto_select_personas`

Recommends which expert personas are most relevant for a plan without running the full council. Uses DeepPlan Scout to analyze persona expertise against your plan.

Parameter	Required	Description
`draft_plan`	Yes	The plan to analyze
`available_personas`	No	Custom persona list (defaults to 4 built-in experts)

Performance Tips

Keep draft plans concise — 200-500 words is ideal for best analysis quality
Always specify tech stack — enables stack-specific recommendations
Add constraints — prevents incompatible suggestions (e.g. “must run on Edge Runtime”)
Deploy your councils — only deployed councils (green dot) are available for MCP auto-selection
Customize your Chair — a well-written Chair persona system prompt produces better synthesis
Use focused councils — a 3-expert council for your specific domain outperforms a generic 5-expert council