Docs / Connect a coding agent

Connect ArchDraw to a coding agent.

This page tells you how to connect ArchDraw to an AI coding agent or a chat client. When the connection is complete, the agent can make, change, validate, and export architecture diagrams.

Client	Recommended method
Claude Code	Plugin
Claude apps	Custom connector
Codex	Plugin
Cursor	Remote (HTTP)
VS Code (GitHub Copilot)	Remote (HTTP)
Gemini CLI	Remote (HTTP)
OpenCode	Remote (HTTP)
Other MCP clients	Remote or local

Before you start

Select a connection type.

ArchDraw has two connection types. Both types give the same 12 tools. Use the remote connection if your client supports it. Use the local connection only if the client cannot connect to a remote server.

Connection type	Address or command	Use it when
Remote (HTTP)	`https://archdraw.hiabhee.online/api/mcp`	The client can connect to a remote MCP server. This is the recommended type. You do not install software.
Local (stdio)	`npx -y @hiabhee/archdraw-mcp-server@1.0.6`	The client can only start a local process.

Requirements

Network access to archdraw.hiabhee.online. This is necessary for the two connection types.
For the local connection only: Node.js 18 or later. To examine your version, type node --version.
You do not need an ArchDraw account or an API key.

CAUTION: For the local connection, you must set API_BASE_URL=https://archdraw.hiabhee.online. If you do not set it, the server starts and shows its tools, but generate_diagram, fix_layout, and preview links do not operate.

NOTE: Each local procedure on this page pins version 1.0.6. A pinned version does not change without your action. To update, change the version number in your configuration.

Plugin

Claude Code

Install the plugin (recommended)

Start Claude Code.
Type this command to add the marketplace:
```
/plugin marketplace add hiabhee/ArchDraw
```
Type this command to install the plugin:
```
/plugin install archdraw@archdraw
```
Restart Claude Code.

The plugin gives the MCP tools and the archdraw skill. It connects to the remote server. It does not install software on your computer.

Add only the MCP server (alternative)

Type this command in your shell:

claude mcp add --transport http archdraw https://archdraw.hiabhee.online/api/mcp

Restart Claude Code.

To make the server available in all projects, add --scope user before archdraw.

Verify the connection

Type this command in your shell:
```
claude mcp list
```
Make sure that archdraw shows as connected.
In Claude Code, type /mcp to see the ArchDraw tools.

Custom connector

Claude apps

This section applies to claude.ai, Claude Desktop, and Claude mobile. These apps connect to remote MCP servers through custom connectors.

Add the custom connector (recommended)

Open Claude on the web or in Claude Desktop.
Go to Settings → Connectors.
Select Add custom connector.
In the name field, type ArchDraw.
In the URL field, type this address:
```
https://archdraw.hiabhee.online/api/mcp
```
Select Add.

The connector is then available in Claude Desktop and Claude mobile with the same account.

NOTE: The availability of custom connectors depends on your Claude plan. On Team and Enterprise plans, it is possible that an owner must add the connector for the organization first.

Claude Desktop with a local server (alternative)

Open the configuration file. On macOS, the file is ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, the file is %APPDATA%\Claude\claude_desktop_config.json.

Add the archdraw entry to mcpServers:

{
  "mcpServers": {
    "archdraw": {
      "command": "npx",
      "args": [
        "-y",
        "@hiabhee/archdraw-mcp-server@1.0.6"
      ],
      "env": {
        "API_BASE_URL": "https://archdraw.hiabhee.online"
      }
    }
  }
}

Save the file.
Fully quit Claude Desktop. On macOS, press Cmd+Q. Closing the window is not sufficient.
Start Claude Desktop again.

Use this procedure only if you cannot use a custom connector. You do not need to clone the ArchDraw repository or build the server.

Verify the connection

Start a new chat.
Open the tools menu and make sure that ArchDraw is on.
Type a request, for example: "Draw a checkout service with Stripe, Postgres, and a Kafka event bus."

Plugin

Codex

This section applies to the Codex CLI, the IDE extension, and the desktop app.

Install the plugin (recommended)

Type these commands in your shell:

codex plugin marketplace add hiabhee/ArchDraw
codex plugin add archdraw@archdraw

Restart Codex.

After you add the marketplace, you can also install the plugin from the Plugins Directory in the ChatGPT desktop app.

NOTE: The Codex plugin uses the local connection. It runs npx -y @hiabhee/archdraw-mcp-server@1.0.6 on your computer. You must have Node.js 18 or later.

Add only the MCP server (alternative)

Type this command in your shell:

codex mcp add archdraw --env API_BASE_URL=https://archdraw.hiabhee.online -- npx -y @hiabhee/archdraw-mcp-server@1.0.6

Restart Codex.

This command writes the entry to ~/.codex/config.toml. You can also write the entry yourself:

[mcp_servers.archdraw]
command = "npx"
args = ["-y", "@hiabhee/archdraw-mcp-server@1.0.6"]

[mcp_servers.archdraw.env]
API_BASE_URL = "https://archdraw.hiabhee.online"

Verify the connection

Type this command in your shell:
```
codex mcp list
```
Make sure that archdraw is in the list.
In the Codex TUI, type /mcp to see the ArchDraw tools.

Remote (HTTP)

Cursor

Add the server

Open ~/.cursor/mcp.json for all projects, or .cursor/mcp.json in the project root for one project.

Add the archdraw entry:

{
  "mcpServers": {
    "archdraw": {
      "url": "https://archdraw.hiabhee.online/api/mcp"
    }
  }
}

Save the file.

Verify the connection

Go to Cursor Settings → Tools & MCP.
Make sure that archdraw shows as connected and that it shows 12 tools.
If you use the Cursor Agent CLI, type this command:
```
cursor-agent mcp list
```

Remote (HTTP)

VS Code (GitHub Copilot)

Add the server

In the project root, open or make the file .vscode/mcp.json.

Add the archdraw entry:

{
  "servers": {
    "archdraw": {
      "type": "http",
      "url": "https://archdraw.hiabhee.online/api/mcp"
    }
  }
}

Save the file.
In the editor, select Start above the archdraw entry.

NOTE: VS Code uses the key servers, not mcpServers.

Verify the connection

Open the Copilot Chat view.
Set the chat mode to Agent.
Select the tools icon.
Make sure that the ArchDraw tools are in the list.

Remote (HTTP)

Gemini CLI

Add the server

Open ~/.gemini/settings.json for all projects, or .gemini/settings.json in the project root for one project.

Add the archdraw entry:

{
  "mcpServers": {
    "archdraw": {
      "httpUrl": "https://archdraw.hiabhee.online/api/mcp"
    }
  }
}

Save the file.
Restart Gemini CLI.

NOTE: Gemini CLI uses the key httpUrl for Streamable HTTP servers. The key url is for SSE servers. Do not use url for ArchDraw.

Verify the connection

In Gemini CLI, type /mcp.
Make sure that archdraw shows as ready and shows its tools.

Remote (HTTP)

OpenCode

OpenCode v1

Open ~/.config/opencode/opencode.json for all projects, or opencode.json in the project root for one project.

Add the archdraw entry under mcp:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "archdraw": {
      "type": "remote",
      "url": "https://archdraw.hiabhee.online/api/mcp",
      "enabled": true
    }
  }
}

Save the file.
Restart OpenCode.

NOTE: This format is for OpenCode v1. OpenCode v2 does not put server names directly under mcp. If you use v2, use the procedure that follows.

OpenCode v2

Open opencode.jsonc in the project root. To make the server available in all projects, use the global configuration.

Add the archdraw entry under mcp.servers:

{
  "mcp": {
    "servers": {
      "archdraw": {
        "type": "remote",
        "url": "https://archdraw.hiabhee.online/api/mcp"
      }
    }
  }
}

Save the file.
Restart OpenCode.

In v2, a server is on by default. To stop it, set "disabled": true. The v1 key enabled does not apply.

Verify the connection

Type this command in your shell:
```
opencode mcp list
```
Make sure that archdraw shows as connected.

Other MCP clients

Use the generic values.

Many other clients support MCP, for example Zed, Cline, and Antigravity. Each client has a different configuration format. Refer to the documentation of your client. Use the values in this section.

Remote (HTTP) values

Field	Value
Name	`archdraw`
Transport	Streamable HTTP
URL	`https://archdraw.hiabhee.online/api/mcp`
Authentication	None

NOTE: The remote server does not support SSE or GET requests. If your client asks for a transport, select Streamable HTTP.

Local (stdio) values

Field	Value
Name	`archdraw`
Command	`npx`
Arguments	`-y`, `@hiabhee/archdraw-mcp-server@1.0.6`
Environment variable	`API_BASE_URL=https://archdraw.hiabhee.online`

Use ArchDraw

Install the ArchDraw skill (optional).

The Claude Code and Codex plugins include the skill. For other agents, you can install the skill separately. The skill tells the agent when to use ArchDraw, to send Mermaid input, and to show the preview link.

Go to the root of your project.

Type this command:

npx skills add hiabhee/archdraw-skill --skill archdraw-diagram

When the CLI asks, select your agent.

To install the skill for all projects, add -g to the command. To update the skill, type npx skills update archdraw-diagram.

Make your first diagram

Type a request to your agent. For example:

"Inspect this repository and draw its architecture. Use evidence from the code. Mark the parts that are not certain."
"Draw a web client, an API gateway, a Node API, and a Postgres database."
"Add a Redis cache between the API and Postgres."
"Change the layout to top-down."

The agent replies with two links. shareUrl is a read-only preview. Anyone with the link can see it. diagramUrl opens the diagram in the ArchDraw editor.

Tools

Tool	Function
`read_me`	Gives the reference guide for the agent. The agent calls it first.
`generate_diagram`	Makes a diagram from Mermaid text or from nodes and edges.
`update_diagram`	Adds, removes, or changes nodes and edges in the current diagram.
`get_diagram_state`	Gives the nodes and edges of the current diagram.
`validate_diagram`	Finds structural problems and gives recommendations.
`fix_layout`	Calculates the layout again with the ArchDraw editor pipeline (Mermaid → Dagre).
`apply_template`	Loads an architecture template.
`list_templates`	Gives the list of templates.
`list_node_types`	Gives the list of component types in the ArchDraw library.
`save_checkpoint`	Saves the current diagram with a name.
`load_checkpoint`	Restores a saved diagram.
`export_diagram`	Exports the diagram as JSON, PNG, or SVG.

Reference

Data and privacy.

Read this section before you connect ArchDraw.

Data that the tools send: The tools send the diagram content that the agent gives them. This includes component names, labels, connections, and Mermaid text. The tools do not read your source files. Your agent reads your files and decides what to put in the diagram.
Preview links: Each new diagram gets a preview link by default. Anyone with the link can see the diagram. The link expires after 7 days. To prevent a link, tell the agent to keep the diagram private. The agent then sets publish: false.
Working sessions: The remote server keeps the current diagram and its checkpoints for 24 hours. Then it deletes them. The local server keeps them in memory until the process stops.
IP address: The server uses your IP address only for rate limits.

WARNING: Do not put passwords, API keys, or other secrets in diagram labels. Anyone with the preview link can see the labels.

Refer to the privacy policy and the terms.

Limits

Limit	Value
Requests to /api/mcp	120 for each minute, for each IP address
Request body size	1 MB
New published diagrams	30 for each hour (anonymous)
Preview link life	7 days
Working session life (remote)	24 hours

Reference

Troubleshooting.

Problem	Possible cause	Corrective action
The agent does not show the ArchDraw tools.	The agent did not load the new configuration.	Fully stop the agent and start it again.
The agent does not show the ArchDraw tools.	The configuration has a JSON or TOML syntax error.	Examine the file for missing commas, brackets, or quotes.
The agent does not show the ArchDraw tools.	The configuration uses the wrong key for the client.	Use the key that this page gives for your client: `url`, `httpUrl`, or `servers`.
The local server does not start.	Node.js is not installed, or the version is older than 18.	Install Node.js 18 or later. Type `node --version` to examine the version.
The local server does not start.	The client cannot find `npx`.	Replace `npx` with its full path. Type `which npx` (macOS, Linux) or `where npx` (Windows) to find the path.
The tools show, but `generate_diagram` fails with "requires API_BASE_URL".	The local configuration does not set `API_BASE_URL`.	Add `API_BASE_URL=https://archdraw.hiabhee.online` to the environment of the server.
The tools show, but there is no preview link.	The agent set `publish: false`, or the publish operation failed.	Tell the agent to publish the diagram. If the response has `linkError`, read the error and try again later.
The server gives HTTP 429.	You are above a rate limit.	Wait some minutes. Then try again.
The connection fails with HTTP 405.	The client uses SSE or GET.	Set the transport to Streamable HTTP.
The agent has the tools, but it does not use them.	The agent does not have the skill.	Install the skill (Install the skill). Or tell the agent: "Use the ArchDraw tools to draw this system."

To report a problem, open an issue on GitHub.

Reference

Self-hosted ArchDraw.

You can connect the tools to your own ArchDraw deployment.

Remote connection: Use https://<your-domain>/api/mcp as the URL.
Local connection: Set API_BASE_URL to https://<your-domain>.
Claude Code plugin: Change the url in plugins/archdraw/.mcp.json.
Codex plugin: Change API_BASE_URL in plugins/archdraw/mcp.json.