Skip to main content
Skip to main content

Local infrastructure context for compatible assistants

MCP integration

Expose a small set of read-only CDK intelligence tools over the Model Context Protocol. The server reads an existing cloud assembly locally, writes responses over standard input/output and does not deploy, call AWS or spend AI credits.

Before connecting

Synthesize the project once. The MCP server intentionally does not run your CDK app, which keeps assistant tool calls deterministic and prevents arbitrary synthesis side effects.

cd /path/to/your-cdk-project
npx cdk synth

# Confirm the server is available
npx cdk-insights mcp --help

Configure an MCP client

Add this server definition to the MCP configuration used by your editor or assistant. Consult that product's documentation for the configuration-file location.

{
  "mcpServers": {
    "cdk-insights": {
      "command": "npx",
      "args": ["-y", "cdk-insights@latest", "mcp"]
    }
  }
}

Pin a version such as cdk-insights@1.61.0 when you want repeatable team tooling. Use @latest when automatic CLI upgrades are intentional.

Available tools

cdk_architecture_graph

Build a JSON or Mermaid resource graph and identify public-to-sensitive dependency paths.

Parameters: projectPath, outDir, format

cdk_reliability_review

Review zonal, dependency, quota and regional-recovery weaknesses.

Parameters: projectPath, outDir

cdk_architecture_document

Return Markdown documentation with a Mermaid diagram, estate summary and attack-path notes.

Parameters: projectPath, outDir, title

cdk_plan_advisor

Estimate monthly credits for supplied change frequency and cache assumptions.

Parameters: projectPath, outDir, model, monthlyInfrastructureChanges, averageChangedResourceRatio, historyDays

Example prompts

The client decides when to call a tool. Being explicit about the project, desired output and decision you are making produces the most useful result.

“Map the CDK architecture in this repository as Mermaid and explain any public-to-sensitive paths.”
“Review cdk.out for zonal and regional resilience gaps. Prioritize high-severity findings.”
“Generate architecture documentation titled “Payments platform” and suggest where it belongs in the repository.”
“Estimate the Pro-plan fit for 12 infrastructure changes per month, 20% changed resources and the Haiku 4.5 model.”

Tool parameters and working directories

  • projectPath defaults to the MCP server process working directory. Set it explicitly when the client starts servers elsewhere.
  • outDir defaults to cdk.out relative to the project path.
  • The graph format defaults to JSON and also accepts Mermaid.
  • The MCP plan advisor requires monthlyInfrastructureChanges. Unlike the interactive CLI plan command, it does not read Git history itself.
  • The plan model defaults to glm-4-7-flash. The changed-resource ratio defaults to 25% when omitted.

Troubleshooting

No cloud assembly found

Run npx cdk synth in the project, or pass the correct projectPath and outDir to the tool.

The client cannot start npx

Use an absolute Node/npx path in the MCP configuration and confirm Node.js 22 or later is available to the client process.

The wrong repository is inspected

Set projectPath explicitly. MCP clients do not always launch servers from the open workspace.

Protocol output is invalid

Do not wrap the command with a script that writes banners or debug messages to stdout; stdout is reserved for JSON-RPC responses.

Documentation

MCP Integration

Docs Home