Skip to content

Quickstart

1. Prerequisites

The installer checks for these and helps you install the missing ones:

Tool Needed for Notes
git, curl cloning + downloading usually preinstalled
an agent client the integration target any of the four below — the installer auto-detects the ones present and refuses to run if it finds none
uv Python servers auto-installed from astral.sh/uv if missing
Go ≥ 1.25 the Go server only needed for irods; pass --no-go to skip it

Supported agent clients:

Client Detected via Integration page
Claude Code claude on PATH Claude Code
Codex CLI codex on PATH Codex CLI
Antigravity agy on PATH, the IDE app, or a ~/.gemini config dir Antigravity
OpenCode opencode on PATH OpenCode

Other clients1 can reuse the manual install steps.

Windows users

Run everything inside WSL (Ubuntu or similar). The installer detects WSL and treats it as Linux. Native PowerShell / cmd are not supported.

2. Install

curl -fsSL https://raw.githubusercontent.com/idss-mesa/docs/main/install.sh | bash

This will:

  1. Detect your platform (Linux / macOS / WSL).
  2. Clone the four repos from idss-mesa into ~/.mesa/repos/.
  3. Create a Python venv at ~/.mesa/.venv and install mesa-ducklake + mesa-mcp + mesa-anyjev.
  4. Build the Go server (irods-mcp-server) into ~/.mesa/bin/.
  5. Register mesa-mcp and irods as local servers, and CyVerse's hosted Formation as formation, with every detected client — Claude Code at user scope, Codex globally, Antigravity and OpenCode via their config files. Restrict targets with --for, e.g. bash -s -- --for claude,codex.

3. Verify

claude mcp list

codex mcp list      # or /mcp inside a Codex session

Open the IDE's Manage MCP Servers panel (or restart agy) and confirm the three servers are listed.

opencode mcp list

You should see mesa-mcp, irods, and formation listed; formation shows as needing authentication until you sign in (step 4). Then, in your agent session, try:

Ping the CyVerse Data Store and list what's in the shared directory.

That exercises mesa-mcp's ds_ping and ds_list_directory tools against the public data.cyverse.org zone — no login needed.

4. Sign in to Formation

formation lets your agent launch Discovery Environment apps and manage analyses. It is hosted by CyVerse and needs a one-time sign-in with your CyVerse account in each client:

Run /mcp inside Claude Code, pick formation, and choose Authenticate — or run claude mcp login formation from a shell.

codex mcp login formation

On a remote machine add --no-browser (Codex 0.156 or newer) and paste back the address your browser lands on.

Run /mcp in agy, or refresh the IDE's MCP servers panel, and sign in to formation. The MESA team has not tested Antigravity's sign-in to Formation; if it fails, use another client.

opencode mcp auth formation

The sign-in callbacks CyVerse documents are claude.ai's and Claude Code's; if another client's sign-in page says Invalid parameter: redirect_uri, see Troubleshooting.

Then try: "Which Discovery Environment apps can I run for JupyterLab?"

5. (Optional) Authenticate the Data Store servers

Anonymous access is read-only on public collections. To let mesa-mcp act as yourself, re-run with your CyVerse credentials:

curl -fsSL https://raw.githubusercontent.com/idss-mesa/docs/main/install.sh \
  | CYVERSE_USERNAME=you CYVERSE_PASSWORD='••••••' bash

The credentials are threaded into the mesa-mcp registration of every client the installer configures. See Credentials for all the options (env vars, ~/.irods, per-server config).

Updating & uninstalling

Re-running the one-liner pulls the latest code and rebuilds — it is safe to run again, keeps your Formation sign-ins, and replaces the local formation server older installs created with the hosted one. Uninstalling removes the three servers from every detected client and (after confirmation) deletes ~/.mesa:

curl -fsSL https://raw.githubusercontent.com/idss-mesa/docs/main/install.sh | bash -s -- --uninstall

  1. OpenClaw support is deferred until its MCP interface can be verified. ↩

Machine-readable versions of this page: Markdown twin · raw source on GitHub · llms.txt · llms-full.txt (whole site). See For AI agents.