Skip to content

Credentials

By default the two local MESA servers, mesa-mcp and irods, connect anonymously to public CyVerse infrastructure (data.cyverse.org, zone iplant, user anonymous). That is enough to read public collections. To write metadata or reach private data as yourself, give them your CyVerse credentials as described below.

formation, the hosted Discovery Environment server, works differently: it has no anonymous access and takes no credentials from you or the installer. Each client signs in to it with your CyVerse account in the browser — see formation below.

Quickest path — env vars at install time

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

The installer threads these into the mesa-mcp registration of every client it configures, as MESA_MCP_IRODS__USER and MESA_MCP_IRODS__PASSWORD.

Where the password ends up

These land in plaintext in each client's config file: ~/.claude.json (Claude Code user scope), ~/.codex/config.toml, $HOME/.gemini/config/mcp_config.json, and ${XDG_CONFIG_HOME:-~/.config}/opencode/opencode.json. Prefer the ~/.irods method below if you don't want the password stored there, and never commit a project-scope .mcp.json containing secrets. The files the installer writes keep their permissions, and a new one is readable by you only; on a shared machine, check them with ls -l.

mesa-mcp & irods — native iRODS auth

Both iRODS servers honor a standard iRODS environment. If you use the CyVerse iCommands, run iinit once to create:

~/.irods/irods_environment.json   # host, zone, user
~/.irods/.irodsA                  # scrambled password

mesa-mcp reads these automatically in stdio mode — no env vars needed.

For irods-mcp-server, edit its stdio config to add credentials:

# ~/.mesa/repos/irods-mcp-server/config-stdio.yaml
irods_host: data.cyverse.org
irods_zone_name: iplant
irods_user_name: you
irods_user_password: ••••••

mesa-mcp — full env reference

mesa-mcp uses MESA_MCP_ env vars (double underscore for nesting). The most useful:

Variable Default Meaning
MESA_MCP_IRODS__HOST data.cyverse.org iRODS host
MESA_MCP_IRODS__ZONE iplant iRODS zone
MESA_MCP_IRODS__USER anonymous username
MESA_MCP_IRODS__PASSWORD — password
MESA_MCP_DUCKLAKE__CATALOG_DSN — DuckLake catalog (duckdb:///path or postgresql://…); blank disables history

Any MESA_MCP_* variable set in your shell at install time is passed through to the server. The full list is in mesa-mcp/.env.example.

formation — sign in with your CyVerse account

Formation is hosted by CyVerse at https://de.cyverse.org/formation/mcp and uses the standard MCP sign-in: OAuth 2.1 with PKCE against CyVerse's Keycloak1. Until you sign in, the client shows formation as needing authentication; its sign-in command (table below) opens the CyVerse sign-in page in your browser, and the client then stores the sign-in and refreshes it.

Client Sign in
Claude Code /mcp inside Claude Code, or claude mcp login formation (--no-browser on a remote machine)
Codex codex mcp login formation (--no-browser on a remote machine, Codex 0.156 or newer)
OpenCode opencode mcp auth formation (not on a remote machine)
Antigravity /mcp in agy or the IDE's MCP servers panel (not tested by MESA)
claude.ai and Claude Desktop Connect on the connector — see claude.ai and Claude Desktop

No password is stored in any config file, and CYVERSE_USERNAME, ~/.irods, and cyverse-login do not apply. Sign in with a CyVerse user account; service-account tokens are refused. The sign-in callbacks CyVerse documents are claude.ai's and Claude Code's; for other clients see Troubleshooting if it fails.

The ~/.formation-mcp.yaml file and the FORMATION_* variables belonged to the old local formation-mcp server and are no longer used; see Moving from the local formation-mcp.

DataCite (optional)

DataCite DOI tools in mesa-mcp only need credentials when you mint/publish DOIs. See the mesa-mcp docs for the DataCite configuration.

  1. Formation README, https://github.com/cyverse-de/formation. ↩

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