# find_matlab() vs connect_matlab() vs shareEngine: MATLAB Engine API Functions Explained

> Understand find_matlab, connect_matlab, and shareEngine in MatlabMCP. Discover shared sessions, establish connections, and execute MATLAB code from Python.

- Repository: [Jigar Bhoye/matlabmcp](https://github.com/jigarbhoye04/matlabmcp)
- Tags: deep-dive
- Published: 2026-03-04

---

**TLDR:** In the MatlabMCP integration, `matlab.engine.shareEngine` prepares a MATLAB session for external access from within MATLAB, `find_matlab()` discovers these shared sessions from Python, and `connect_matlab()` establishes the actual communication channel, returning an engine object for executing code.

The MatlabMCP repository bridges large language model tools with live MATLAB environments using the **MATLAB Engine API for Python**. Understanding the differences between `find_matlab()`, `connect_matlab()`, and `shareEngine` is critical for troubleshooting connection issues and understanding the architectural flow. These three functions operate on different sides of the Python-MATLAB boundary and serve distinct purposes in the discovery and connection pipeline.

## The Three Functions Explained

### matlab.engine.shareEngine (MATLAB-Side Setup)

**`matlab.engine.shareEngine`** runs inside the MATLAB desktop or console, not in Python. This command marks the current MATLAB process as shareable by creating a named pipe or socket that external programs can locate.

Before starting the MatlabMCP server, users must execute this command in their MATLAB session:

```matlab
matlab.engine.shareEngine

```

According to the repository's [`README.md`](https://github.com/jigarbhoye04/matlabmcp/blob/main/README.md) (lines 47-50), this step is mandatory. The command returns `true` or `1` if the session is already shared, which you can verify using `matlab.engine.isEngineShared`.

### matlab.engine.find_matlab() (Python-Side Discovery)

**`matlab.engine.find_matlab()`** operates on the Python side to scan the local machine for MATLAB sessions that have been shared. It returns a **list of session name strings** (e.g., `['MATLAB_1', 'MATLAB_2']`) that can be passed to `connect_matlab()`.

In [`main.py`](https://github.com/jigarbhoye04/matlabmcp/blob/main/main.py) at line 27, MatlabMCP uses this function to discover available sessions:

```python
import matlab.engine

names = matlab.engine.find_matlab()  # Returns ['MATLAB_1', ...]

if not names:
    # Handle error: no shared sessions found

    pass

```

If no shared sessions exist, the function returns an empty list `[]`, which the code checks to abort with a clear error message.

### matlab.engine.connect_matlab() (Python-Side Connection)

**`matlab.engine.connect_matlab(session_name)`** opens a communication channel to a specific shared MATLAB session identified by the `session_name` parameter obtained from `find_matlab()`. It returns an **engine object** (`eng`) that enables Python to call MATLAB functions, access the workspace, and execute code.

In [`main.py`](https://github.com/jigarbhoye04/matlabmcp/blob/main/main.py) at line 39, the implementation connects to the first discovered session:

```python
eng = matlab.engine.connect_matlab(names[0])

```

This engine object exposes methods like `eng.evalc()` and `eng.workspace`, which MatlabMCP tools use to execute MATLAB code asynchronously via `asyncio.to_thread()`. If the connection fails (e.g., the session vanished), it raises `matlab.engine.EngineError`.

## How the Functions Work Together in MatlabMCP

These functions operate in a strict sequence to establish the Python-MATLAB bridge:

1. **User prepares MATLAB:** Execute `matlab.engine.shareEngine` in MATLAB to publish the session name to the operating system.
2. **Python discovers sessions:** The MatlabMCP server calls `find_matlab()` in [`main.py`](https://github.com/jigarbhoye04/matlabmcp/blob/main/main.py) (line 27) to retrieve the list of published session names.
3. **Python connects:** The server selects the first available name and calls `connect_matlab()` in [`main.py`](https://github.com/jigarbhoye04/matlabmcp/blob/main/main.py) (line 39) to obtain the engine object.
4. **Tool execution:** Subsequent MCP tool implementations (`runMatlabCode`, `getVariable`, etc.) use this `eng` object to issue non-blocking calls to the shared MATLAB instance.

## Error Handling and Return Values

Each function handles failures differently based on its operating context:

- **shareEngine:** Returns a boolean indicating if the session was already shared. Throws a MATLAB error if the Engine API is missing.
- **find_matlab():** Returns an empty list `[]` when no shared sessions exist. The MatlabMCP server explicitly checks `if not names:` to provide user-friendly error messaging.
- **connect_matlab():** Raises `matlab.engine.EngineError` on connection failure. The server catches this exception and exits with diagnostic information.

## Summary

- **`matlab.engine.shareEngine`** is a MATLAB command that makes a session discoverable by external processes.
- **`matlab.engine.find_matlab()`** is a Python function that scans for and lists all shared MATLAB session names.
- **`matlab.engine.connect_matlab()`** is a Python function that attaches to a specific shared session and returns an executable engine object.
- MatlabMCP relies on this sequence: shareEngine → find_matlab → connect_matlab, implemented in [`main.py`](https://github.com/jigarbhoye04/matlabmcp/blob/main/main.py) and documented in [`README.md`](https://github.com/jigarbhoye04/matlabmcp/blob/main/README.md).

## Frequently Asked Questions

### What happens if I don't run shareEngine before starting MatlabMCP?

The Python server will call `find_matlab()` and receive an empty list, causing the application to abort with an error indicating no shared MATLAB sessions were found. You must execute `matlab.engine.shareEngine` in your MATLAB console first.

### Can I connect to multiple MATLAB sessions simultaneously?

While `find_matlab()` returns a list of all shared sessions, the current MatlabMCP implementation in [`main.py`](https://github.com/jigarbhoye04/matlabmcp/blob/main/main.py) connects only to the first available session (`names[0]`). You could modify the code to spawn multiple engine objects by calling `connect_matlab()` with different session names from the list.

### Why does find_matlab() return an empty list even when MATLAB is running?

MATLAB must be explicitly shared using `matlab.engine.shareEngine`. Simply having MATLAB open does not make it discoverable. Additionally, permission issues or firewall restrictions on the named pipe/socket can prevent the session from appearing in the scan results.

### Is matlab.engine.shareEngine required for every new MATLAB session?

Yes. Each MATLAB process must independently run `matlab.engine.shareEngine` to become visible to Python clients. If you restart MATLAB, you must re-run this command before the MatlabMCP server can reconnect.