# What Happens When the Revit Plugin Is Not Running or a Connection to It Fails

> Learn what happens when the Revit plugin fails to connect. Discover how the MCP server handles errors gracefully without crashing, ensuring smooth workflow.

- Repository: [MCP servers for Revit/revit-mcp](https://github.com/mcp-servers-for-revit/revit-mcp)
- Tags: how-to-guide
- Published: 2026-02-16

---

**When the Revit plugin is not running, the MCP server attempts a TCP connection to localhost:8080, times out after 5 seconds, and returns a structured error message to the calling tool instead of crashing.**

The `revit-mcp` server acts as a bridge between AI assistants and Autodesk Revit, relying on a local TCP socket to communicate with a running Revit plugin. Understanding the failure behavior when the Revit plugin is not running or a connection to it fails is critical for building resilient integrations.

## Connection Architecture Overview

The connection lifecycle is managed by two core utilities in the `src/utils/` directory:

- **[`SocketClient.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/SocketClient.ts)**: Implements the low-level JSON-RPC client using Node.js `net.Socket`. It handles socket creation, command serialization, response matching by request ID, and error logging.
- **[`ConnectionManager.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/ConnectionManager.ts)**: Orchestrates connection attempts through the `withRevitConnection` helper, implementing timeout logic and cleanup.

When a tool needs to communicate with Revit, it invokes `withRevitConnection`, which attempts to open a socket to `localhost:8080`.

## Failure Path When the Revit Plugin Is Not Running

When the Revit plugin is not running, the TCP handshake to port 8080 cannot complete. The system follows this strict failure path:

1. **Tool Invocation**: A tool like `tag_all_walls` calls `withRevitConnection` to execute an operation.
2. **Socket Initialization**: [`ConnectionManager.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/ConnectionManager.ts) creates a new `RevitClientConnection` instance targeting `localhost:8080`.
3. **Connection Attempt**: The code attaches event listeners for `"connect"` and `"error"`, then calls `revitClient.connect()`.
4. **Timeout Trigger**: Since no process is listening on port 8080, the connection hangs until the 5-second timeout fires.

### The 5-Second Timeout Mechanism

The timeout is hardcoded in [`src/utils/ConnectionManager.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/ConnectionManager.ts):

```typescript
setTimeout(() => {
  reject(new Error("连接到Revit客户端失败"));
}, 5000);

```

This rejects the connection promise with the message "连接到Revit客户端失败" (Connection to Revit client failed). The promise rejection propagates up the call stack to the tool's error handler.

### Error Propagation to Tools

Each tool wraps the `withRevitConnection` call in a `try/catch` block. For example, in [`src/tools/tag_all_walls.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/tools/tag_all_walls.ts):

```typescript
try {
  const response = await withRevitConnection(async (client) => {
    return await client.sendCommand("tag_walls", args);
  });
  return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
} catch (error) {
  return {
    content: [{ 
      type: "text", 
      text: `Wall tagging failed: ${error instanceof Error ? error.message : String(error)}` 
    }],
  };
}

```

The result is a structured MCP content object containing the error message, which the client (ChatGPT, Claude, or a CLI) can display to the user without crashing the server.

## Handling Transient Connection Failures

If the Revit plugin stops running after a connection is established, [`SocketClient.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/SocketClient.ts) detects the disconnect through socket events:

```typescript
this.socket.on("error", (error) => {
  console.error("RevitClientConnection error:", error);
  this.isConnected = false;
});

this.socket.on("close", () => {
  this.isConnected = false;
});

```

When `isConnected` is `false`, subsequent tool calls trigger a new connection attempt via `withRevitConnection`, which will again timeout if Revit remains unavailable. This ensures the server remains stable and can recover once Revit is restarted.

## Summary

- When the Revit plugin is not running, the MCP server attempts to connect to `localhost:8080` and fails after a **5-second timeout**.
- The error message **"连接到Revit客户端失败"** propagates through `withRevitConnection` to the calling tool.
- Tools catch these errors and return **structured error payloads** instead of crashing the server.
- [`SocketClient.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/SocketClient.ts) logs connection errors to the console and sets `isConnected = false` when the socket closes.
- The architecture ensures **graceful degradation**—the server remains operational and retries connections on subsequent tool calls.

## Frequently Asked Questions

### How long does the server wait before reporting a connection failure?

The server waits exactly **5 seconds** before timing out. This is hardcoded in [`src/utils/ConnectionManager.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/ConnectionManager.ts) using `setTimeout`. If the Revit plugin does not accept the TCP connection within this window, the promise rejects with "连接到Revit客户端失败".

### Can I change the port or host where the server looks for the Revit plugin?

Currently, the host and port (`localhost:8080`) are hardcoded in the connection utilities. To change them, you would need to modify [`src/utils/ConnectionManager.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/ConnectionManager.ts) where `RevitClientConnection` is instantiated, or update the [`SocketClient.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/SocketClient.ts) defaults. Future versions may expose these as environment variables.

### Will the MCP server crash if Revit closes unexpectedly while a tool is running?

No. The server uses `try/catch` blocks in every tool implementation to handle promise rejections. If Revit closes mid-operation, [`SocketClient.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/SocketClient.ts) emits an error or close event, sets `isConnected = false`, and the active command promise rejects. The tool catches this and returns a structured error message to the client without terminating the server process.

### What error message will I see in my AI assistant or CLI when Revit is not running?

You will see a message formatted as `[Tool Name] failed: 连接到Revit客户端失败`. For example, if using the wall tagging tool, the response will be `Wall tagging failed: 连接到Revit客户端失败`. This is returned as a text content block in the MCP response structure.