01 · Install
Add the skill and the MCP server.
The skill provides reusable instructions for architecture diagrams. The MCP server adds diagram tools to your agent. Install the skill from your project root; then use the command for your coding agent below.
Install the ArchDraw skill
The Skills CLI will ask which supported agent to install it for. From the project root, the default install is local to this project.
Install skill
Terminal
npx skills add hiabhee/archdraw-skill --skill archdraw-diagramTo install globally, add -g to the command.
Connect MCP
Set API_BASE_URL so the server can use ArchDraw’s diagram generation and layout API.
Codex CLI
Terminal
codex mcp add archdraw --scope user --env API_BASE_URL=https://archdraw.hiabhee.online -- npx -y @hiabhee/archdraw-mcp-serverClaude Code
Terminal
claude mcp add --scope local --transport stdio --env API_BASE_URL=https://archdraw.hiabhee.online archdraw -- npx -y @hiabhee/archdraw-mcp-serverCursor · .cursor/mcp.json
JSON
{
"mcpServers": {
"archdraw": {
"command": "npx",
"args": ["-y", "@hiabhee/archdraw-mcp-server"],
"env": {
"API_BASE_URL": "https://archdraw.hiabhee.online"
}
}
}
}Codex above installs for your user account. To limit it to the current project, change --scope user to --scope project. Claude Code above saves a local entry for this project.
archdraw, with command npx, arguments -y @hiabhee/archdraw-mcp-server, and environment variable API_BASE_URL=https://archdraw.hiabhee.online.The MCP process runs on your machine and sends diagram requests to the API URL you configure. For a self-hosted ArchDraw instance, set that variable to your instance URL.
02 · Verify
Check that the tools loaded.
Restart your coding agent after adding the server. Then check its MCP list or ask it to list the ArchDraw tools. You should see tools such as generate_diagram, update_diagram, and list_node_types.
Codex
codex mcp listIn the Codex TUI, open /mcp.
Claude Code
claude mcp listInside Claude Code, use /mcp.
Cursor
Open Settings → Tools & MCP and check that ArchDraw is connected. From Cursor Agent CLI, you can also run cursor-agent mcp list.
03 · Try it
Ask for a diagram grounded in your code.
Start with one of these prompts, then refine the generated architecture in conversation.
“Inspect this repository and map its architecture. Use evidence from the code and mark anything uncertain.”
“Trace a request from the web client through the backend to persistent storage. Include the main services and external calls.”
“Add Redis between the API and Postgres, show which requests use the cache, and update the diagram.”
Updates
Keep the skill current.
Run the Skills CLI from the project where you installed the skill. For a global install, add -g.
Update the ArchDraw skill
Terminal
npx skills update archdraw-diagramTroubleshooting
When setup doesn’t show up.
I ran npx archdraw-agent setup and nothing happened.
That setup command can exit without registering the MCP server. Use the manual skill and MCP steps above; the Codex and Claude commands will write the server entry into the respective agent configuration.
The MCP server is missing from the agent.
Confirm the archdraw entry exists in the right configuration, then fully restart the agent. For Codex or Claude Code, rerun that client’s list command above and check for an error next to the server.
The tools load, but generation fails.
Check that the MCP entry includes API_BASE_URL, that the URL is reachable, and that Node.js 18 or newer is installed. Then restart the agent and try again.
My agent has MCP but doesn’t use the skill.
Confirm the archdraw-diagram skill is installed for the same agent and project. You can also prompt: “Use the ArchDraw diagram skill to map this system.”