Coding agents on your computer
Claude Code and Codex reach RunMat through RunMat Desktop. While the app is open and signed in, it serves RunMat's MCP tools at http://127.0.0.1:47862/mcp. The coding agent reads and edits files, runs code, inspects variables, figures and run history, checks and runs .fea studies, and checks, inspects, renders and edits .part, .assembly, .drawing and .circuit files in the Projects open in RunMat's windows. It gets the same answers as the RunMat Agent in the app. Runs appear in the app as they happen, and runs made in the app appear in the coding agent's run history.
The tools work only while RunMat is open. When the app is closed, the RunMat plugin tells the coding agent to ask you to open it.
Connect Claude Code or Codex
- Install RunMat Desktop, open it and sign in.
- Open the Project you want the coding agent to work in.
- Open Settings › Connections. Under On this computer, choose Connect next to Claude Code or Codex.
- Restart Claude Code or Codex, then enter
/mcpand confirm that therunmatserver is connected. - Ask the coding agent for work in the Project. The first time it asks to use a Project, RunMat shows the request in Connected agents. Choose Allow while this project is open or Always allow.
Connecting installs the RunMat plugin for that coding agent. The plugin adds the runmat MCP server and RunMat's skills. If the page says an older RunMat plugin is installed, choose Update.
Install the plugin from a terminal
RunMat Desktop keeps a copy of each plugin in ~/.runmat/plugins. To install one by hand:
# Claude Code
claude plugin marketplace add ~/.runmat/plugins/claude-code
claude plugin install runmat@runmat --scope user
# Codex
codex plugin marketplace add ~/.runmat/plugins/codex
codex plugin add runmat@runmatRestart the coding agent after installing.
How access is controlled
- RunMat listens on the loopback address only, so other computers can't reach it.
- Each request must carry this installation's access token. RunMat Desktop writes the token to
~/.runmat/mcp-headers.json, which only your user account can read, and the plugin reads it from there. - RunMat refuses requests from web pages, so a site open in your browser can't call the tools.
- A coding agent gets no Project until you allow it for that Project in Connected agents. Until then, only
runmat.get_statusanswers, without the Project's name or contents; every other tool returns an error that tells the agent to ask you. Allow while this project is open lasts until you close or switch the Project or quit RunMat. Always allow applies whenever that Project is open, until you choose Stop or Remove. Turn off access pauses both. - The coding agent works as the user signed in to RunMat Desktop. Each call that runs code or changes a file counts as an MCP client call on that user's allowance; reading, listing, inspecting and checking don't. Study runs and circuit simulations use that user's simulation allowance. See Usage and limits.
To stop a coding agent working in a Project, choose Stop next to it in Connected agents. To remove the plugin, choose Disconnect in Settings › Connections.
Other MCP clients on your computer
Another MCP client on the same computer can use the same server if it supports Streamable HTTP with custom headers:
| Setting | Value |
|---|---|
| Name | runmat |
| Transport | Streamable HTTP |
| URL | http://127.0.0.1:47862/mcp |
| Header | Authorization: Bearer <token>, with the token from ~/.runmat/mcp-headers.json |
Read the token from the file when the client starts rather than copying it into a configuration file you share.
Troubleshooting
- The
runmatserver isn't listed or can't connect. Open RunMat Desktop. On macOS you can runopen -a RunMat. Then reconnect the server from/mcpor restart the coding agent. - RunMat says sign-in is required. Sign in to RunMat Desktop.
- RunMat says no Project is open. Open the Project folder in RunMat. With more than one window open, the coding agent asks which Project to use.
- The connection is refused. Open Settings › Connections and connect the coding agent again. The page also says when another program is using port 47862. In that case, close that program and restart RunMat.