sdd-mcp — Claude Code MCP server: what it does, how to install
Brings Spec-Driven Development to coding agents. It stops automated code generation until you approve written specs and plans.
claude mcp add --env SDD_PROJECT_ROOT=<SDD_PROJECT_ROOT> --env SDD_WORKSPACES_ROOT=<SDD_WORKSPACES_ROOT> --transport stdio sdd-mcp -- npx -y @juanklagos/sdd-mcpWhat sdd-mcp does
This server connects your assistant to a structured specs/ directory and a bitacora/ decision log. Specs come first. The workflow enforces a strict boundary: no production code gets written before spec.md and plan.md pass verification and receive explicit consent.
The system relies on validation checks to inspect requirements and record consent before implementation starts. The package runs directly via npx using @juanklagos/sdd-mcp.
Without configured SDD_PROJECT_ROOT and SDD_WORKSPACES_ROOT environment variables, the server cannot locate your project root.
What it helps with
- establish formal requirements in
spec.mdbefore writing code - verify consistency between execution plans and task specifications
- record architecture trade-offs and rationale inside
bitacora/ - prevent agent code changes before approval gate validation
Example prompts for the agent
- Verify
spec.mdagainstplan.mdand run the gate check before coding. - Record our database schema decision in
bitacora/decisiones/.
How to install sdd-mcp
Platform CLI
claude mcp add --env SDD_PROJECT_ROOT=<SDD_PROJECT_ROOT> --env SDD_WORKSPACES_ROOT=<SDD_WORKSPACES_ROOT> --transport stdio sdd-mcp -- npx -y @juanklagos/sdd-mcpReplace <…> with your own values
Platform CLI
codex mcp add sdd-mcp --env SDD_PROJECT_ROOT=<SDD_PROJECT_ROOT> --env SDD_WORKSPACES_ROOT=<SDD_WORKSPACES_ROOT> -- npx -y @juanklagos/sdd-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"sdd-mcp": {
"command": "npx",
"args": [
"-y",
"@juanklagos/sdd-mcp"
],
"env": {
"SDD_PROJECT_ROOT": "<SDD_PROJECT_ROOT>",
"SDD_WORKSPACES_ROOT": "<SDD_WORKSPACES_ROOT>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"sdd-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@juanklagos/sdd-mcp"
],
"env": {
"SDD_PROJECT_ROOT": "<SDD_PROJECT_ROOT>",
"SDD_WORKSPACES_ROOT": "<SDD_WORKSPACES_ROOT>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e SDD_PROJECT_ROOT=<SDD_PROJECT_ROOT> -e SDD_WORKSPACES_ROOT=<SDD_WORKSPACES_ROOT> sdd-mcp npx -y @juanklagos/sdd-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about sdd-mcp
How to install sdd-mcp in Claude Code?
Run claude mcp add sdd-mcp -- npx -y @juanklagos/sdd-mcp. If you need environment variables, run `claude mcp add --env SDD_PROJECT_ROOT=<SDD_PROJECT_ROOT> --env SDD_WORKSPACES_ROOT=<SDD_WORKSPACES_ROOT> --transport stdio sdd-mcp -- npx -y @juanklagos/sdd-mcp`.
What does sdd-mcp do?
It enforces the Spec-Driven Development cycle, blocking code generation until written specifications and plans pass validation checks.
Which environment variables does sdd-mcp need?
The server uses SDD_PROJECT_ROOT and SDD_WORKSPACES_ROOT to resolve project directories and workspace paths.
