# Uxarray Mcp Server

> Model Context Protocol (MCP) server for unstructured mesh analysis using UXarray and Academy-py.

- **Type:** MCP server
- **Install:** `agentstack add mcp-uxarray-uxarray-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [UXARRAY](https://agentstack.voostack.com/s/uxarray)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [UXARRAY](https://github.com/UXARRAY)
- **Source:** https://github.com/UXARRAY/uxarray-mcp-server

## Install

```sh
agentstack add mcp-uxarray-uxarray-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# UXarray MCP Server

An MCP server that lets an AI assistant (Claude Code, Claude Desktop, Cursor,
or any MCP client) analyze unstructured climate meshes with
[UXarray](https://uxarray.readthedocs.io/) — locally on your machine, or
remotely on an HPC system you have access to.

```text
┌─────────────┐  stdio  ┌──────────────┐                    ┌─────────────────┐
│  AI client  │ ◀─────▶ │ uxarray-mcp  │ ◀── Globus ──────▶ │  HPC endpoint   │
│  (Claude…)  │   pipe  │ (your laptop)│    Compute (opt)   │ (Slurm/PBS node)│
└─────────────┘         └──────────────┘                    └─────────────────┘
```

> **What the AI can do.** Open meshes and datasets, compute area / zonal mean
> / vorticity / divergence, subset, remap, plot, and run multi-step workflows.
> All as natural-language prompts.

> **Local by default; HPC is opt-in.** Everything runs on your machine unless
> you configure a [Globus Compute](https://www.globus.org/compute) endpoint.
> The remote option only becomes available once such an endpoint exists —
> running one requires an account and allocation on that HPC system, though a
> shared/service-account endpoint can let authorized users submit without their
> own login.

> **⚠️ What the AI can access.** Any file you (or your HPC account) can read.
> Any compute the configured endpoint can submit. Outputs are written to your
> disk. **See [SECURITY.md](SECURITY.md) before connecting any remote endpoint.**

---

## Pick your path

You are most likely one of:

1. **Local user** — laptop only, no HPC. → [Local install](#local-install).
2. **HPC user, endpoint already exists** — someone at your lab gave you a
   Globus Compute endpoint UUID. → [Local install](#local-install), then
   [docs/remote-hpc.md](docs/remote-hpc.md).
3. **HPC user, your own personal endpoint** — you have a Globus identity and
   shell access to an HPC machine, and want to stand up an endpoint just for
   yourself. → [Local install](#local-install), then
   [docs/operating-an-endpoint.md](docs/operating-an-endpoint.md#solo-personal-endpoint-quickstart).
4. **Group / shared endpoint operator** — you're standing one up for a team,
   project, or lab. → [Local install](#local-install), then the full
   [docs/operating-an-endpoint.md](docs/operating-an-endpoint.md) including
   service-account migration and the MEP allowlist.

---

## Local install

Five steps. Each is one command unless noted.

### Step 1 — Install the package

Pick one. `uv` is the easiest; `pip` works too.

```bash
# Recommended
uv tool install --python 3.12 uxarray-mcp

# Or from a fresh clone (developer path)
git clone https://github.com/UXARRAY/uxarray-mcp-server.git
cd uxarray-mcp-server && uv sync --python 3.12
```

> **Why `--python 3.12`?** The server uses Globus Compute to submit work to
> HPC endpoints, and Globus Compute's serializer is fragile across Python
> minor versions — a 3.13 submitter against a 3.12 endpoint worker raises
> `WorkerLost` on non-trivial payloads. HPC sites broadly ship 3.12 conda
> stacks today, so we pin the install to match. Tracking removal of this pin
> at [globus/globus-compute#2139](https://github.com/globus/globus-compute/issues/2139).
> `uv` downloads 3.12 automatically if your system doesn't have it.

### Step 2 — Write a starter config

```bash
uxarray-mcp setup
```

Creates `~/.config/uxarray-mcp/config.yaml` with sensible defaults. Local mode
needs nothing more.

### Step 3 — Connect your AI client

**Claude Desktop**

```bash
uxarray-mcp install-claude        # merges the mcpServers block into your config
# or
uxarray-mcp install-claude --print-only   # prints the JSON to paste manually
```

Restart Claude Desktop. The `uxarray` server should appear in Settings →
Developer.

**Claude Code**

```bash
claude mcp add uxarray --transport stdio -- uxarray-mcp serve
```

Then `/mcp` in Claude Code; pick `uxarray`.

**Cursor / other MCP clients**

Add an MCP server entry pointing at `uxarray-mcp serve` over stdio. See your
client's MCP docs.

### Step 4 — Sanity check

```bash
uxarray-mcp doctor
```

Prints a JSON diagnostic report. With no endpoints configured it reports a
passing local setup and skips the remote checks; the process exits `0` when
`passed` is true.

### Step 5 — Ask the AI to do something

In your client, try:

> "Open `` and plot the mesh."

That's it for local use.

---

## Going beyond your laptop

If you have an HPC account at a national lab or university cluster with
[Globus Compute](https://www.globus.org/compute) available:

| You want to … | Read this |
|---|---|
| Connect to an endpoint someone else set up | **[docs/remote-hpc.md](docs/remote-hpc.md)** |
| Stand up your own endpoint | **[docs/operating-an-endpoint.md](docs/operating-an-endpoint.md)** |
| Understand the security model first | **[SECURITY.md](SECURITY.md)** |

Both paths assume you've finished local install above.

---

## What the MCP exposes

Intent-shaped tools, not raw UXarray bindings:

- `get_capabilities` — what can I do with this mesh?
- `analyze_dataset` — deterministic first-look: inspect, validate, area, zonal mean, plots.
- `run_analysis` — one operation at a time (gradient, curl, subset, remap, …).
- `plot_dataset` — mesh, geographic, variable, or zonal-mean plots.
- `diagnose_endpoint`, `probe_path_access` — endpoint health + file readability.
- `run_workflow`, `resume_workflow`, `get_status`, `get_result`, `manage_session` —
  persisted sessions and multi-step workflows.

Tools that can run remotely take `use_remote: bool` and optional `endpoint: str`.
The dispatcher falls back to local if the endpoint is unhealthy.

Full schema: [docs/tools.md](docs/tools.md).

---

## CLI reference

| Command | Purpose |
|---|---|
| `uxarray-mcp serve` | Run the MCP server (used by your AI client) |
| `uxarray-mcp setup` | Write a starter config |
| `uxarray-mcp endpoints add NAME UUID` | Register a Globus Compute endpoint |
| `uxarray-mcp endpoints list` | Show configured endpoints |
| `uxarray-mcp doctor` | Validate local + (optionally) remote setup |
| `uxarray-mcp install-claude` | Merge or print the Claude Desktop config block |

---

## Risks (read before relying on output)

AI agents can misread prompts, pick the wrong file, get units wrong (e.g.,
sphere-radius scaling on derivatives), or run long jobs on your HPC
allocation. uxarray-mcp does **not** guarantee correctness of agent-driven
analysis. You are responsible for:

- Verifying numerical results before publishing.
- Reviewing what files the agent opens.
- Monitoring HPC job submissions against your allocation.

For the security model (what the agent and the endpoint operator can access),
see **[SECURITY.md](SECURITY.md)**.

---

## Development

```bash
uv sync --extra hpc --extra docs --dev
uv run pre-commit run --all-files
uv run pytest tests/ --ignore=tests/test_remote_agent.py
uv run sphinx-build -b html docs docs/_build/html
```

Release process: [docs/release.md](docs/release.md).

## License

See [LICENSE](LICENSE).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [UXARRAY](https://github.com/UXARRAY)
- **Source:** [UXARRAY/uxarray-mcp-server](https://github.com/UXARRAY/uxarray-mcp-server)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-uxarray-uxarray-mcp-server
- Seller: https://agentstack.voostack.com/s/uxarray
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.