Claude Code integration¶

MESA registers mesa-mcp and irods as local stdio MCP servers: Claude Code launches each binary as a subprocess and talks to it over standard input/output. It registers formation as a remote HTTP server: Formation is hosted by CyVerse at https://de.cyverse.org/formation/mcp, and you sign in to it once with your CyVerse account. Claude Code is one of four clients MESA supports — see also Codex CLI, Antigravity, and OpenCode, and claude.ai and Claude Desktop for connectors.

Scopes¶

The installer uses user scope (-s user) so the servers are available in every Claude Code project on your machine. The three scopes Claude Code supports:

Scope	Stored in	Visible to
`local`	your user config, keyed to the current project	just you, just this project
`user`	your user config	you, every project (MESA default)
`project`	`.mcp.json` committed in the repo	everyone who clones the repo

Override with MCP_SCOPE, e.g. MCP_SCOPE=project to drop a shareable .mcp.json into the current directory instead.

Managing the servers¶

claude mcp list                 # show all servers + health
claude mcp get mesa-mcp         # show one server's config
claude mcp remove mesa-mcp -s user

The registration MESA creates¶

User-scope registrations live in ~/.claude.json; project scope lands in a .mcp.json committed at the repo root.

{
  "mcpServers": {
    "mesa-mcp":  { "type": "stdio", "command": "~/.mesa/.venv/bin/mesa-mcp",
                   "args": ["--transport", "stdio"], "env": {} },
    "irods":     { "type": "stdio", "command": "~/.mesa/bin/irods-mcp-server",
                   "args": ["-c", "~/.mesa/repos/irods-mcp-server/config-stdio.yaml"], "env": {} },
    "formation": { "type": "http", "url": "https://de.cyverse.org/formation/mcp" }
  }
}

mesa-ducklake is not listed here

mesa-ducklake is a library imported by mesa-mcp, not a separate MCP server. Its capabilities surface through mesa-mcp's mesa_ducklake_* tools. See its page.

Conflicting scopes¶

If claude mcp list warns that a server is "defined in multiple scopes", you have the same name registered more than once (e.g. an older hand-rolled entry plus the MESA one). Keep the one you want and remove the rest:

claude mcp remove mesa-mcp -s user
claude mcp remove mesa-mcp -s local

Hosted servers and connectors¶

Formation¶

Formation runs only as CyVerse's hosted server; the installer registers it for you. To add it by hand (in every project, at user scope):

claude mcp add --transport http --scope user formation https://de.cyverse.org/formation/mcp

claude mcp list shows it as Needs authentication until you sign in. Run /mcp inside Claude Code, pick formation, and choose Authenticate; or run claude mcp login formation from a shell (add --no-browser on a remote machine and paste the redirect URL back). Claude Code stores the sign-in and refreshes it¹.

Upgrading from an older MESA install? Its formation entry was a local server that no longer works, and claude mcp add at user scope fails while that entry exists. Re-run the installer, or run claude mcp remove formation -s user first. See Moving from the local formation-mcp.

claude.ai connectors¶

If you are signed in to Claude Code with a claude.ai subscription, connectors you added on claude.ai — such as a CyVerse Formation connector — are available in Claude Code automatically. A server you registered in Claude Code itself takes precedence over a connector with the same URL, so the connector is hidden rather than listed twice. Connectors are not loaded when Claude Code runs with an API key or another model provider.

CyVerse Data Store (iRODS)¶

CyVerse also hosts Data Store MCP endpoints, which the MESA featured apps register alongside the local servers²:

# public data under /iplant/home/shared, no sign-in
claude mcp add --transport http --scope user irods-public https://mcp-public.cyverse.ai/mcp

# your own data: CyVerse's pre-registered OAuth client, then sign in
claude mcp add --transport http --scope user --client-id mcp-client --callback-port 8990 \
  irods-auth https://mcp.cyverse.ai/mcp
claude mcp login irods-auth

The names avoid a clash with the installer's local irods. Hosted mesa-mcp (Streamable HTTP / SSE behind CyVerse Keycloak OIDC) is documented in the mesa-mcp repo; it requires authentication. The MESA installer builds mesa-mcp and irods locally because they work without signing in and give you live, editable source.

Claude Code MCP documentation, https://code.claude.com/docs/en/mcp. ↩
MESA app images, Claude Code MCP config, https://github.com/idss-mesa/cli/blob/main/bash/configs/claude.json. ↩

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