Formation (hosted)¶

Endpoint: https://de.cyverse.org/formation/mcp · Run by: CyVerse · Source: cyverse-de/formation · Registered as: formation

Formation is the CyVerse Discovery Environment's own MCP server¹. CyVerse hosts it, so there is nothing to install or build: point your client at the URL and sign in with your CyVerse account. Your agent can then find and launch Discovery Environment apps, follow and stop analyses, and read, write, and describe files in the CyVerse Data Store, always as you and with your own permissions.

CyVerse's setup page covers Claude Code, a custom connector on claude.ai and in Claude Desktop, Antigravity, and other clients that take an mcpServers block. The sign-in callbacks CyVerse documents, though, are claude.ai's and Claude Code's (http://localhost…). You can register it in every client MESA supports, but whether Codex, OpenCode, and Antigravity can complete the CyVerse sign-in is not yet confirmed (see Troubleshooting).

Add it to your client¶

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

[mcp_servers.formation]
url = "https://de.cyverse.org/formation/mcp"
tool_timeout_sec = 600   # launches can wait up to 9 minutes

{
  "mcp": {
    "formation": {
      "type": "remote",
      "url": "https://de.cyverse.org/formation/mcp",
      "enabled": true
    }
  }
}

{
  "mcpServers": {
    "formation": {
      "serverUrl": "https://de.cyverse.org/formation/mcp"
    }
  }
}

Sign in¶

Until you sign in, the client lists formation as needing authentication. Run its sign-in command (in your client's tab above, or the list below), which opens the CyVerse sign-in page in your browser. Log in with your CyVerse username and password and you are sent back to the client. Behind this is standard MCP sign-in: OAuth 2.1 with PKCE against CyVerse's Keycloak, and automatic client registration, so there is no API key or client ID to set up¹.

• No password, environment variable, ~/.irods file, or cyverse-login is involved.
• Sign in, and later sign in again if calls fail with authentication errors, with /mcp or claude mcp login formation, codex mcp login formation, opencode mcp auth formation, or Connect on claude.ai. The client stores the sign-in and refreshes it.
• Sign in with a CyVerse user account. Keycloak service-account (client-credentials) tokens are refused.
• No CyVerse account yet? Register for free at https://user.cyverse.org.

Tools¶

Good to know¶

• Launching apps. launch_app_and_wait waits up to 5 minutes by default and never more than 9 minutes. Unless the agent passes overall_job_type, the tool first checks for required parameters the request did not supply and lists them instead of launching, so the agent can ask you; with overall_job_type it launches directly. Batch (non-interactive) jobs return as soon as they are submitted; check them with get_analysis_status.
• Text only. browse_data returns file contents into the conversation, so whatever it reads is sent to your model provider. It reads at most 1 MiB at a time and continues with offset and limit; images, archives, and other binary files cannot be read.
• Deleting. delete_data moves items to your Data Store trash (its own description says deletions are permanent; they are not). Non-empty folders need recurse.
• Metadata. set_metadata with replace replaces only the attributes you set and keeps the others. CyVerse system attributes (names starting with ipc) are hidden and cannot be written.
• Everything is yours. Analyses Formation launches appear in the Discovery Environment and on the MESA Portal's Analyses page, and output goes to your analyses folder.
• Approving tools. The tools carry no read-only or destructive hints, so your client treats them all alike. Approve delete_data, upload_file, set_metadata, stop_analysis, and launch_app_and_wait call by call rather than "always".

Moving from the local formation-mcp¶

Earlier versions of the MESA installer built formation-mcp and registered it as a local stdio server that called Formation's REST API. CyVerse replaced that API with this hosted MCP server in mid-2026, so the local server no longer works: it exits with Configuration error: FORMATION_BASE_URL is required, or its tools fail with login failed with status 404.

Re-run the installer and it replaces the old entry with the hosted one in every client and deletes ~/.mesa/bin/formation-mcp:

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

To switch by hand instead, remove the old entry first, then add the hosted one as shown above:

~/.formation-mcp.yaml and the FORMATION_* environment variables are no longer used; you can delete them, along with ~/.mesa/repos/formation-mcp.

Troubleshooting¶

More in Troubleshooting.

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