Astah MCP Server

Connect Astah to external AI clients

Starting with version 11, the AI Chat Copilot plugin is included by default. This plugin lets you connect Astah to an external AI service via MCP (Model Context Protocol).
So that you can work with your Astah models using your preferred AI clients.

What is MCP?
MCP (Model Context Protocol) is a standard protocol for connecting AI clients to tools and applications. For more details, see the official MCP documentation.

What you can do with an MCP Server

You can:

• Use your preferred AI client to work with Astah models
• Generate, update, and analyze diagrams from outside Astah
• Bring external context such as documents, specifications, or files into AI-assisted modeling
• Combine diagram operations with documentation, code, and review workflows

For scenarios and prompt examples for design workflows, model analysis, documentation generation, and code integration — see: Detailed Scenarios & Prompt Examples (Currently for Astah Professional and UML only)

Configure Astah

You can enable the MCP Server in a few minutes.

1. Launch Astah version 11 or later.
   
   
2. Open the Chat Copilot pane
   Select the Chat Copilot tab in the Extra view which you can open from [View] ▸ [Show/Hide Extra View].
   
   
   
   
3. Settings
   Click Settings to configure the setting to connect Astah with AI service.
   
   
   
4. Open MCP section to enable integration with MCP-compatible AI clients.
   

• MCP Integration:
  Enable this option to allow external AI clients to connect to Astah via MCP.
  You must separately register the MCP server in the external tools or agents you use.
  
  
• MCP Port:
  Specify the port number used by the MCP Server.
  If you change this value, update the port setting in your AI client as well.

NOTE:
If you plan to use an external AI client via MCP, you only need to configure the MCP section. To use the in-app Chat Copilot, configure the other sections as well.

Configure Clients

Verified Clients you can connect with Astah via MCP

The following MCP-compatible clients have been verified to work with Astah:

• Claude Code – VS Code
• GitHub Copilot Chat – VS Code
• Cline – VS Code
• Copilot CLI
• Codex
• Claude Desktop

Other MCP clients

You can also use other clients that support MCP. If your preferred client is not listed above, configure it using the MCP server URL and port.

Claude Code – VS Code

On a computer where Claude Code is installed, run the following command:

```bash
claude mcp add --transport http --scope user astah-mcp http://localhost:3099/mcp
```

The –scope option supports three types:

• local: Enabled only for the current working folder (local workspace). Default
• project: Saved per project. You can include .mcp.json in your repository to share the configuration with your team.
• user: Enabled for the entire user account on this PC. The same MCP server can be used from any folder.

GitHub Copilot Chat – VS Code

1. Open VS Code (with the GitHub Copilot Chat extension installed).
2. Open the Command Palette:
   • Windows/Linux: Ctrl + Shift + P
   • macOS: Cmd + Shift + P
3. Search for and run MCP: Add Servers.
4. Configure the following items:
   • Server type: Select HTTP
   • URL: Enter http://localhost:3099/mcp
   • Server ID: Enter astah-mcp
   • Where to install the MCP server setting: Choose either
     • Local (current workspace only), or
     • Global (all workspaces)

Cline – VS Code

1. Open VS Code.
2. In the Activity Bar on the left, select the Cline extension tab.
3. In the Cline panel, click the settings icon to open the MCP settings.
4. Click Configure MCP Servers.
5. Add the following to the configuration file:

```json
{
  "mcpServers": {
    "mcp-remote": {
      "url": "http://localhost:3099/mcp",
      "type": "streamableHttp",
      "disabled": false
    }
  }
}
```

Copilot CLI

1. Launch Copilot CLI.
2. Run the /mcp add command.
3. Set the following items:
   • Server Name: astah-mcp
   • Server Type: [2] HTTP
   • URL: http://localhost:3099/mcp

When you set Server Type to HTTP, you will be able to edit the URL.
You do not need to configure HTTP Headers.
Configure Tools only if necessary for your use case.

Codex

On a computer where Codex is installed, run the following command.

• Windows: run it in Command Prompt
• macOS/Linux: run it in Terminal

```bash
codex mcp add astah-mcp npx mcp-remote http://localhost:3099/mcp
```

Claude Desktop

1. Launch Claude Desktop and open the menu in the top-left.
2. Select Settings → Developer → Edit Config.
3. Add the following to the configuration file (claude_desktop_config.json) and save it:

```json
{
  "mcpServers": {
    "astah-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3099/mcp",
        "--allow-http"
      ]
    }
  }
}
```

4. Quit Claude Desktop completely via Quit.
5. Restart Claude Desktop.

⚠️ If you close the window using the “×” button, the app may keep running in the background. Please make sure to quit it from the menu.

Start

1. Launch Astah
2. Launch AI Service

⚠️ Important: Start Astah before launching the AI client. If the AI client starts first, it may fail to connect to the MCP Server.

For prompt examples for design workflows, model analysis, documentation generation, and code integration — see: Detailed Scenarios & Prompt Examples (Currently for Astah Professional and UML only)

Troubleshooting

Issue: Astah Cannot Connect to MCP Server

Checks:

• Is Astah running?
• Is MCP integration enabled in the Settings?

Solution:

1. Confirm the MCP integration is enabled in the Settings.
2. Restart Astah.
3. Restart the AI Client.

Issue: Port is already in use

Cause:

Another application is using the same port number.

Solution:

1. Change the port number in the Settings (e.g., to 3010).
2. Restart Astah.
3. Update the port setting in the AI client as well.

Issue: AI Client does not detect Astah

Cause:

The startup order is incorrect, or the settings have not been applied.

Solution:

1. Fully quit the AI client, including any background processes.
2. Launch Astah and confirm that the MCP server is enabled in the Settings.
3. Start the AI client.
4. Check the connection status by sending new prompts.

Issue: Node.js Version Error (Claude Desktop)

Cause:

A version of Node.js older than 18 is installed.

Solution:

1. Download and install the LTS version from the official Node.js website.
2. After installation, run node –version in Command Prompt / Terminal to confirm the version.
3. Restart Astah.
4. Restart Claude Desktop.

Notes and Limitations

• Astah MCP Server relies on an external AI service.
• AI-generated results may be incomplete or inaccurate.
• Always review and validate diagrams before use.
• Do not enter confidential or sensitive information unless permitted by your organization’s policies.

Token Limitations

• AI services have an upper limit on the number of tokens they can process.
• Sending or receiving very large specifications or model data in a single request may:
  • Reduce response quality
  • Cause timeout or errors
  • Make processing unstable
• Try to adjust your prompts so that the exchanged information does not become excessively long.

Updating Astah MCP Server

Astah MCP Server is provided as a plugin.
When updates with bug fixes or improvements become available, we provide an updated plugin .jar file. Follow the steps below to update MCP Server to the latest version.

How to Update Astah MCP Server

1. Download the latest plugin .jar file (file name: astah-copilot-x.x.x.jar).
   
   
2. Drag and drop the .jar file into the Astah window while Astah is running.
   
   
3. Restart Astah to apply the update.

Current Version Information

Astah MCP Server is bundled with the AI Chat Copilot plugin. For the latest version of each Astah edition, see the Version & Update Information section on the AI Chat Copilot page.

How to Check Your Installed Plugin Version

1. Open [Plugin] → [Installed Plugin].
   
   
   
2. A list of installed plugins will appear.
   
   
3. Locate “Astah AI Chat Copilot” and check the Version column.