> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Argus MCP

> Connect Claude Code, Codex, or any MCP client to Argus, and hand CAD and CAE work to a specialist engineering agent.

Argus exposes itself as a local [MCP](https://modelcontextprotocol.io) server.
Any agent that speaks MCP — Claude Code, Codex, or your own — can call Argus as
a **sub-agent**: the general-purpose agent keeps the overall task, and hands the
CAD and simulation work to Argus.

A typical split: Claude Code writes the test-rig firmware and updates the
requirements doc. When it needs the mounting bracket's peak stress, it asks
Argus. Argus opens the part in SolidWorks, runs the study, checks the result,
and returns the answer with screenshots.

```mermaid theme={null}
flowchart LR
    subgraph machine["Your machine"]
        direction LR
        HOST["Claude Code / Codex<br/>(orchestrating agent)"]
        APP["Argus app<br/>platform agents + your login"]
        CAD["CAD/CAE software"]
    end

    HOST <-->|"MCP: run · streamed steps · answer"| APP
    APP <-->|"drives"| CAD
```

## Why delegate to Argus

General-purpose coding agents are good at code, files, and planning. Driving
engineering software is a different job. It needs live access to the open
model, knowledge of each vendor's quirks, and checks at every step. If your
agent writes CAD macros from scratch, you get scripts that look right and fail
on the real model. Delegating gets you a specialist built for this work.

> **Domain-specific agents**
>
> Each platform has its own agent — SolidWorks, NX, CATIA, Abaqus, Ansys,
> COMSOL, Fluent, and more. Each one has tools and skills for that software,
> so it doesn't have to guess at a vendor API.

> **Fewer mistakes on CAD/CAE work**
>
> Argus works against the open model, not a guess about it. It reads feature
> trees, mesh stats, and solver output. It checks its own work with
> screenshots and model queries, and recovers when an operation fails.

> **A clean context for your main agent**
>
> The many tool calls behind a mesh-and-solve stay inside Argus. Your main
> agent gets back a short answer and images, not thousands of tokens of API
> traffic. That leaves its context free for the rest of the task.

> **Guardrails built in**
>
> Changes to the model go through Argus's confirmation gates. Your client can
> answer them, or Argus can resolve them safely on its own. Your Argus login
> and credits stay inside the app.

**Each agent stays in its lane.** Your coding agent keeps the repo, the
scripts, and the overall plan. Argus does the engineering-software work it was
built for. Each one is good at its own half of the task.

## Prerequisites

**1. Open Argus and sign in**

The MCP server runs inside the desktop app, so the app must be open while
your agent uses it.

**2. Turn on Developer access**

In **Settings → Developer access**, turn it on. The app starts a local MCP
server and writes its connection details to a descriptor file:

| OS | Descriptor path |
| - | - |
| macOS | `~/Library/Application Support/nexus/mcp-gateway.json` |
| Windows | `%APPDATA%\nexus\mcp-gateway.json` |
| Linux | `~/.config/nexus/mcp-gateway.json` |

```json mcp-gateway.json theme={null}
{
  "protocol_version": 1,
  "endpoint": "http://127.0.0.1:53817/mcp",
  "token": "3f9c…",
  "app_version": "1.42.0",
  "transport": "mcp-streamable-http"
}
```

**3. (Optional) Check readiness**

If you have the SDK installed (`pip install cosmon-agent-sdk`), run
`cosmon doctor`. It confirms the app is reachable and the agent runtime is
ready, and lists the platform agents you can call.

> [!WARNING]
>
> **The endpoint and token change every time Argus launches.** Toggling Developer
> access also issues a new token. Don't hard-code them in a config file. Use the
> launchers below: they read the descriptor each time you start your agent, so
> the connection is always current.

## Connect Claude Code

This shell function reads the descriptor and starts Claude Code with Argus
attached as an MCP server named `argus`. Add it to `~/.zshrc` or `~/.bashrc`:

```bash ~/.zshrc theme={null}
argus-claude() {
  local desc="${COSMON_SDK_DESCRIPTOR:-$HOME/Library/Application Support/nexus/mcp-gateway.json}"
  local cfg
  cfg=$(python3 - "$desc" <<'PY'
import json, sys
d = json.load(open(sys.argv[1]))
print(json.dumps({"mcpServers": {"argus": {
    "type": "http",
    "url": d["endpoint"],
    "headers": {"Authorization": f"Bearer {d['token']}"},
}}}))
PY
  ) || { echo "Argus descriptor not found — is the app open with Developer access on?"; return 1; }
  MCP_TOOL_TIMEOUT="${MCP_TOOL_TIMEOUT:-3600000}" claude --mcp-config "$cfg" "$@"
}
```

On Linux, set the default path to `~/.config/nexus/mcp-gateway.json` instead.
Run `argus-claude` in place of `claude`, then type `/mcp` to confirm `argus` is
connected.

`MCP_TOOL_TIMEOUT` lets an Argus run last up to an hour (the value is in
milliseconds). Meshing and solving often take longer than the default MCP tool
timeout. Raise the value for long solves.

> **Windows (PowerShell)**
>
> Add this to your PowerShell profile (`notepad $PROFILE`):
>
> ```powershell theme={null}
> function argus-claude {
>   $d = Get-Content "$env:APPDATA\nexus\mcp-gateway.json" | ConvertFrom-Json
>   $cfg = @{ mcpServers = @{ argus = @{
>     type    = "http"
>     url     = $d.endpoint
>     headers = @{ Authorization = "Bearer $($d.token)" }
>   } } } | ConvertTo-Json -Depth 5 -Compress
>   $env:MCP_TOOL_TIMEOUT = "3600000"
>   claude --mcp-config $cfg @args
> }
> ```

### Make Argus a Claude Code subagent

To make delegation explicit, define a subagent whose only tools are Argus's.
Claude Code then hands CAD/CAE tasks to it. The many tool calls behind each
task stay out of your main conversation.

```markdown .claude/agents/argus.md theme={null}
---
name: argus
description: CAD and CAE specialist. Use for any task that opens, inspects, modifies, meshes, simulates, or post-processes a model in engineering software (SolidWorks, NX, CATIA, Abaqus, Ansys, COMSOL, Fluent, etc.).
tools: mcp__argus__run, mcp__argus__end_session, mcp__argus__list_chats
---

You delegate engineering-software work to Argus through the `run` tool.

- Write the prompt as an engineering outcome, not a sequence of clicks:
  "Run a static study on bracket.sldprt with a 500 N load on the top face and
  report the peak von Mises stress and where it occurs."
- Pass `agent` for the platform (e.g. "solidworks", "abaqus") when it's known.
- Pass absolute file paths in `attachments`.
- For follow-ups on the same model, reuse a `session` id so Argus keeps the
  context; call `end_session` when done.
- Report Argus's numbers and conclusions as it gave them. Don't infer results
  it didn't report.
```

## Connect Codex

Codex reads MCP servers from `~/.codex/config.toml`, and you can override any
setting with `-c`. This launcher passes the current endpoint and token each
time Codex starts:

```bash ~/.zshrc theme={null}
argus-codex() {
  local desc="${COSMON_SDK_DESCRIPTOR:-$HOME/Library/Application Support/nexus/mcp-gateway.json}"
  local endpoint token
  endpoint=$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["endpoint"])' "$desc") || {
    echo "Argus descriptor not found — is the app open with Developer access on?"; return 1; }
  token=$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["token"])' "$desc")
  ARGUS_MCP_TOKEN="$token" codex \
    -c "mcp_servers.argus.url=\"$endpoint\"" \
    -c 'mcp_servers.argus.bearer_token_env_var="ARGUS_MCP_TOKEN"' \
    -c 'mcp_servers.argus.tool_timeout_sec=3600' \
    "$@"
}
```

`tool_timeout_sec` lets an Argus run last up to an hour. Codex's default tool
timeout is far too short for a solve.

To tell Codex when to delegate, add guidance to your project's `AGENTS.md`:

```markdown AGENTS.md theme={null}
## CAD / CAE work

Never script CAD or simulation software directly. For any task that touches an
engineering model — inspecting, editing, meshing, solving, or post-processing —
call the `argus` MCP server's `run` tool with the outcome you need, the
platform `agent` (e.g. "solidworks", "abaqus"), and absolute paths in
`attachments`. Use Argus's reported values as the source of truth.
```

## Connect any other MCP client

Any client that supports **Streamable HTTP** can connect:

| Setting | Value |
| - | - |
| Transport | Streamable HTTP |
| URL | `endpoint` from the descriptor |
| Header | `Authorization: Bearer <token>` (from the descriptor) |
| Host | Loopback only — the client must run on the same machine as Argus |

Read the descriptor when the client starts, not once at install time.

## What the server exposes

**run** `tool`

Runs an engineering task and returns the transcript (with each tool step as a
`▶ <step>` line), plus any images the run produced as MCP image content.

**arguments**

**prompt** `string` *required*

What you want the agent to do.

**agent** `string`

Platform agent, e.g. `solidworks`, `abaqus`, `fluent`. Omit for the default
agent, which routes the task. `cosmon doctor` lists the available agents.

**attachments** `string[]`

Paths to files on the machine running Argus.

**session** `string`

Pass the same id across calls to keep a multi-turn conversation; Argus
remembers earlier turns. Omit for a one-shot run.

**allow\_questions** `boolean`

Whether your client answers the agent's clarifying questions. Defaults to
`true` when the client supports elicitation.

**allow\_confirms** `boolean`

Whether your client answers confirmation requests. Defaults to `true` when
the client supports elicitation.

**ephemeral** `boolean`

Delete the conversation when the run (or session) ends. Defaults to `false`.

**end\_session** `tool`

Ends a multi-turn session. The conversation persists unless it was started
with `ephemeral: true`.

**list\_chats** `tool`

Lists the conversations created through MCP, newest first. Your own app chats
are not included.

**delete\_chat** `tool`

Deletes a conversation created through MCP. It can't touch chats you started
in the app.

**nexus\://status** `resource`

Login state, available agents, model, and readiness. Wait for both
`runtime_ready` and `tool_server_ready` before calling `run`.

The server also streams each tool step and text delta as MCP progress
notifications. Clients that show progress let you watch the run as it happens.

## Questions and confirmations

Argus sometimes needs input: a clarifying question ("which face is the fixed
support?") or approval before it changes the model. How these are handled
depends on your client:

* **Clients that support MCP elicitation** pass the question or confirmation to
  you. Each prompt is open for 120 seconds. After that, Argus proceeds on its
  best judgment, and an unanswered confirmation counts as declined.
* **Clients without elicitation** run **unattended**. Argus doesn't ask
  questions, approves safe actions, and declines dangerous ones (deleting
  bodies, overwriting files).

Use `allow_questions: false` or `allow_confirms: false` on `run` to switch off
either kind of prompt.

## Limits to know

* **One run at a time.** Argus drives a single instance of your CAD/CAE
  software, so a second `run` that starts while one is in progress fails with a
  `busy` error. If your orchestrator runs subagents in parallel, send Argus
  tasks one after another.
* **Same machine.** The server only accepts loopback connections. Your agent
  must run on the machine where Argus and your engineering software are
  installed.
* **Long runs need long timeouts.** Argus has no run time limit of its own.
  If the client times out, it cancels the run, and Argus stops cleanly. Set your
  client's MCP tool timeout to cover your longest solve. Some hosts have a fixed
  timeout of a few minutes that you can't change. With those, use the CLI
  instead (below).

## Alternative: call the CLI from a shell

Any agent that can run shell commands can call Argus through the `cosmon` CLI,
with no MCP setup. There are no timeouts to configure and no endpoint to
refresh:

```bash theme={null}
cosmon run "Report the mass and bounding box of bracket.sldprt" \
  --agent solidworks --attach ./bracket.sldprt -q
```

`-q` prints only the finished transcript, so the calling agent gets one clean
block of output. See the [CLI reference](/sdk/cli) for all flags.

## Next steps

> **[Argus SDK overview](/sdk/overview)**
>
> How the local connection model works, and how to drive Argus from Python.

> **[Supported software](/getting-started/supported-software)**
>
> The CAD, CAE, and PLM platforms Argus can drive.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.