Generate IaC Architecture Diagrams Inside Claude Code and Cursor with InfraSketch MCP

TL;DR: Install the InfraSketch MCP server with one command (claude mcp add infrasketch -- npx infrasketch-mcp), then ask Claude Code to diagram any Terraform, Kubernetes, or Pulumi code without leaving your editor. The diagram opens in your browser, your code never leaves your machine.

The context-switching problem: diagrams while you code

AI editors like Claude Code, Cursor, and Windsurf have gotten surprisingly good at infrastructure work. You can paste a 2,000-line Terraform module into context, ask it to refactor a subnet configuration, and get a working diff in seconds. But ask it to show you an architecture diagram of that same code? Until recently, the answer was "open a browser, paste it somewhere else, render it there."

That break is annoying in a specific way. It's not just the thirty seconds — it's that you lose the thread. The AI has been building context about your codebase, your constraints, what you're trying to do. When you jump to another tool and come back, you're starting that context fresh.

The InfraSketch MCP server fixes this by adding diagram generation as a tool your AI assistant can call natively. Two tools: generate_diagram and detect_iac_format. Ask Claude "can you show me a diagram of this?" and it calls the tool, gets a URL, and includes it in its response. You never left the editor.

What is MCP and why it matters for infrastructure teams

Model Context Protocol (MCP) is an open standard developed by Anthropic that lets AI assistants communicate with external tools and services through a standardized interface. Instead of an AI assistant being limited to the text in its context window, MCP lets it call out to tools — read files, run searches, query APIs, generate artifacts — and incorporate the results back into the conversation.

For infrastructure teams the implication is straightforward: your AI assistant can now do things that previously required leaving the editor:

• Look up the current state of a Terraform resource in a cloud account
• Check a security scanner for misconfigurations
• Generate an architecture diagram of whatever code it's currently looking at
• Figure out what IaC format a file is before processing it

MCP servers are lightweight processes that run locally alongside your editor. They communicate with the AI assistant over a stdio or SSE transport — there's no cloud intermediary. The InfraSketch MCP server is published as infrasketch-mcp on npm and requires only Node.js to run.

Installing infrasketch-mcp (npx, global, Claude Code one-liner)

The fastest way to install is the Claude Code one-liner, which registers the MCP server in your Claude Code configuration in a single command:

claude mcp add infrasketch -- npx infrasketch-mcp

This tells Claude Code to start the InfraSketch MCP server on demand using npx, which downloads and runs the package without a global install. The server starts fresh each session and exits when Claude Code closes — no persistent daemon.

If you prefer a global install to avoid npx startup overhead:

npm install -g infrasketch-mcp

Then reference it directly in your MCP configuration as infrasketch-mcp instead of npx infrasketch-mcp.

Setup: Claude Code (claude mcp add command + settings.json method)

After running the claude mcp add command above, the server is registered automatically. To verify it's registered correctly, run:

claude mcp list

You should see infrasketch in the list. If you prefer to configure it manually, or if you're deploying a shared configuration to a team, edit your Claude Code MCP settings file at ~/.claude/settings.json and add the server to the mcpServers object:

{
"mcpServers": {
"infrasketch": {
"command": "npx",
"args": ["infrasketch-mcp"]
}
}
}

For project-level configuration (useful when you want to check the MCP config into your repository so the whole team gets it automatically), create or edit .claude/settings.json in your project root:

{
"mcpServers": {
"infrasketch": {
"command": "npx",
"args": ["infrasketch-mcp"],
"description": "Generate architecture diagrams from IaC code"
}
}
}

After editing the settings file, restart Claude Code for the changes to take effect. The MCP server will be available in all sessions in that project.

Setup: Cursor and Windsurf

Cursor uses the same MCP configuration format. Create or edit ~/.cursor/mcp.json (for global configuration) or .cursor/mcp.json in your project root:

{
"mcpServers": {
"infrasketch": {
"command": "npx",
"args": ["infrasketch-mcp"]
}
}
}

In Cursor, go to Settings → MCP to verify the server appears and shows a green connected status. You may need to click "Reload MCP Servers" after saving the config file.

Windsurf follows the same pattern. Edit ~/.windsurf/mcp.json with the same configuration block. Once the server is connected, both Cursor's Composer and Windsurf's Cascade will have access to the InfraSketch tools and can call them in response to natural language prompts about your infrastructure code.

Node.js required: The MCP server requires Node.js 18 or later. Run node --version to check. If you're using a version manager like nvm or fnm, make sure the active version is 18+ before starting your editor.

The generate_diagram tool in action (with example prompt + example output)

Once the MCP server is connected, you can ask Claude to generate diagrams in natural language. You don't need to know the tool name or its parameters — just describe what you want:

Generate a diagram for this terraform code:

resource "aws_vpc" "main" {
cidr_block = "10.0.0.0/16"
tags = { Name = "main-vpc" }
}

resource "aws_subnet" "public" {
vpc_id            = aws_vpc.main.id
cidr_block        = "10.0.1.0/24"
availability_zone = "us-east-1a"
}

resource "aws_internet_gateway" "igw" {
vpc_id = aws_vpc.main.id
}

resource "aws_route_table" "public" {
vpc_id = aws_vpc.main.id
route {
cidr_block = "0.0.0.0/0"
gateway_id = aws_internet_gateway.igw.id
}
}

resource "aws_route_table_association" "public" {
subnet_id      = aws_subnet.public.id
route_table_id = aws_route_table.public.id
}

Claude will call the generate_diagram MCP tool with the code and format, and return something like:

Here's your architecture diagram:

**[View Interactive Diagram](https://infrasketch.cloud/#eJyVVdtu2zgQffdXEH...)**

The diagram shows:
- **VPC** (10.0.0.0/16) as the top-level container
- **Public Subnet** (10.0.1.0/24) in us-east-1a inside the VPC
- **Internet Gateway** attached to the VPC
- **Route Table** with a default route (0.0.0.0/0) pointing to the IGW
- **Route Table Association** linking the public subnet to the route table

You can click the link to open an interactive, zoomable diagram in your browser.

The diagram URL is a permanent shareable link. The iframe embed lets you paste the diagram directly into documentation, Notion, Confluence, or any HTML page. The AI assistant also provides a human-readable summary of what the diagram shows, which is useful for accessibility and for quickly confirming the rendering is correct without opening a browser.

The detect_iac_format tool

The second tool exposed by the MCP server is detect_iac_format. This is useful when you have an ambiguous file and want the AI to determine its format before processing it. You can invoke it explicitly:

What IaC format is this file?

apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
spec:
replicas: 3
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.21

The tool returns the detected format (kubernetes in this case) along with a confidence score. Claude Code will then use this information to call generate_diagram with the correct type parameter, producing an accurate diagram for Kubernetes resources rather than trying to parse it as Terraform or CloudFormation.

In practice, the format detection runs automatically when you ask for a diagram — you rarely need to invoke it explicitly. It's most useful in agentic workflows where code is being passed programmatically and the format isn't known in advance.

Real workflow: reviewing a Terraform PR with Claude + InfraSketch

Concrete example. A teammate opens a PR adding an ECS cluster with autoscaling to an existing VPC. You're reviewing it in Claude Code:

1. Ask Claude to show you what changed: "What's different in the terraform/ directory compared to main?" It reads the diff and summarizes.
2. "Generate a diagram of the full terraform/environments/prod/ directory so I can see how the ECS cluster fits in." Claude calls generate_diagram, gets a URL back.
3. Click the URL. You get an interactive, zoomable diagram — ECS cluster, task definitions, ALB, target groups, VPC subnets, security groups, all in one view.
4. Back in Claude: "The ECS tasks are in the public subnet. Intentional?" Claude already has all the code in context and can answer immediately.
5. Your review comment is specific — "the ECS tasks should be in the private subnet per our networking standards, the security group on line 43 is too permissive" — not just "looks good" or a vague worry about networking.

Reading HCL line by line is fine for small changes. For anything spanning multiple resources and subnets, the diagram gets you oriented in about ten seconds instead of ten minutes.

For teams that want this diagram to appear automatically on every PR without any manual step, the GitHub Action (pandey-raghvendra/infrasketch@v4) posts the diagram as a PR comment whenever Terraform files change.

How the URL is generated (no upload, privacy-first, works offline)

The MCP server uses the same URL-encoding approach as the CLI and browser tool. When generate_diagram is called:

• The code is serialized into a JSON envelope with the detected format
• The JSON is compressed with gzip and base64-encoded
• The encoded string is appended as a URL fragment to https://infrasketch.cloud/
• The resulting URL is returned to the AI assistant, which includes it in its response

The MCP server process runs entirely on your machine. It never makes outbound HTTP requests to InfraSketch servers. The URL it generates encodes your code in the fragment, which — by the HTTP specification — is never transmitted to a server. When you open the URL in a browser, the InfraSketch web app decodes and renders the diagram entirely client-side.

This means the tool works in air-gapped environments (as long as your browser can load the web app), needs no API keys, stores nothing server-side, and leaves no audit trail. If your team has strict data residency requirements, that matters. Cloud-hosted diagramming APIs typically process your code on their servers — this one doesn't, by design.

Combining MCP with CLI and embed for full workflow

The MCP server, CLI, and embed component are designed to complement each other across different parts of the development lifecycle:

• MCP server — Use during active coding and code review inside your AI editor. Get diagrams inline without leaving your editor or conversation.
• CLI (npx infrasketch) — Use for quick local checks, scripting, and CI pipelines. See the CLI guide for full details.
• GitHub Action — Use for automated PR comments. Zero friction for reviewers — the diagram appears without anyone running a command.
• Embed web component — Use for documentation, runbooks, and internal wikis. Keep diagrams live and synchronized with the source code.

In practice, a team that's using all four ends up with: MCP for daily coding and reviews, CLI for pre-commit sanity checks and one-off scripting, the GitHub Action for automated PR comments, and embed for the internal docs wiki. Every diagram comes from the same source of truth. Nothing ever gets uploaded.

Supported formats and limitations

The MCP server supports the same eight IaC formats as the web tool and CLI:

Format	Auto-detected	Multi-file support	Notes
terraform	Yes (.tf extension)	Yes (concatenated)	Best coverage of all formats
kubernetes	Yes (apiVersion field)	Yes	Helm chart values not rendered
pulumi	Partial (Pulumi.yaml)	Partial	Heuristic extraction from source
cloudformation	Yes (Resources key)	Yes	Nested stacks shown as references
cdk	Partial	Partial	Works best with synthesized output
bicep	Yes (.bicep extension)	Yes	Modules shown as references
terragrunt	Yes (terragrunt.hcl)	Yes	Module dependency graph included
docker-compose	Yes (services key)	Single file	Networks and volumes visualized

The main limitation to be aware of is code size. The URL fragment approach has a practical ceiling around 2 MB of raw IaC content before browser URL limits become a concern. For most individual modules and services this is not an issue, but for very large monorepos you should point the tool at a specific subdirectory rather than the entire repository root.

FAQ

Does the MCP server require any API key or account?

No. Completely free, no authentication. It runs locally and talks to your AI editor over stdio. No InfraSketch account, no key, no usage limits. Just Node.js.

Does my Terraform code get sent to InfraSketch servers?

No. The MCP server encodes your code into a URL fragment. Fragments are never transmitted in HTTP requests — that's part of the HTTP spec, not something special we're doing. The InfraSketch web app decodes and renders everything in the browser. The InfraSketch server only ever serves the static HTML/JS/CSS files, same as any website.

Can I use the MCP server with VS Code or other editors?

Anything that supports Model Context Protocol over stdio will work. Claude Code, Cursor, and Windsurf are the most common. VS Code has MCP support in some extensions. For editors that don't support MCP at all, the CLI and browser tool still cover most of the same use cases.

What happens if the diagram looks wrong?

The MCP server passes your code to the renderer exactly as-is — no modification, no interpretation. So if the diagram is wrong, it's the renderer's parsing that's off, not how the AI called the tool. Open the interactive diagram in your browser, check what's there, and if you spot a bug file it on GitHub with the example code.

Can I use the MCP server in a team setting with a shared configuration?

Yes, and this is actually the easiest setup. Add the MCP config to .claude/settings.json (Claude Code) or .cursor/mcp.json (Cursor) at the project root and check it into your repo. Anyone who clones gets it automatically. Since it uses npx, nobody needs to install anything manually.

Diagram your infrastructure without leaving your editor Add the InfraSketch MCP server to Claude Code in one command, or try the browser tool right now — no account needed. Try InfraSketch Free →