--- title: "For AI agents" description: "How agents should consume these docs — llms.txt, per-page Markdown with OKF frontmatter, trust signals — and why to call the MESA MCP servers for data." type: Reference tags: - about - ai-agents - OKF - llms.txt generated: by: "claude-code/2.1.294" at: "2026-10-08T00:00:00Z" sources: - id: okf-spec resource: "https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md" title: "Open Knowledge Format (OKF) v0.2 specification" author: "team:google-cloud" - id: llmstxt resource: "https://llmstxt.org" title: "The /llms.txt convention" author: "team:answer-ai" - id: mcp-spec resource: "https://modelcontextprotocol.io/specification" title: "Model Context Protocol specification" author: "team:modelcontextprotocol" status: stable stale_after: "2027-04-08T00:00:00Z" --- # For AI agents This site is published for people **and** for AI agents. The documentation source is an [Open Knowledge Format (OKF) v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) knowledge bundle[^okf-spec], and the deployed site exposes that structure directly. If you are an agent (or you are wiring one up), consume the documentation through the endpoints below rather than scraping rendered HTML. ## This site documents an MCP stack The MESA stack — [mesa-mcp](https://idss-mesa.github.io/docs/servers/mesa-mcp/) and [irods-mcp-server](https://idss-mesa.github.io/docs/servers/irods-mcp-server/), which run locally, with the [mesa-ducklake](https://idss-mesa.github.io/docs/servers/mesa-ducklake/) library behind mesa-mcp, and [Formation](https://idss-mesa.github.io/docs/servers/formation-mcp/), which CyVerse hosts — *is* agent tooling. If what you actually want is CyVerse data — Data Store collections, AVU metadata, ontology terms, Discovery Environment apps and analyses — do not scrape these pages: connect the servers and call their tools. * **Every server, every detected client:** `curl -fsSL https://raw.githubusercontent.com/idss-mesa/docs/main/install.sh | bash` registers `mesa-mcp` and `irods` as local `stdio` servers and Formation by URL — see the [Quickstart](https://idss-mesa.github.io/docs/quickstart/). * **One server by hand:** `claude mcp add mesa-mcp -s user -- ~/.mesa/.venv/bin/mesa-mcp --transport stdio` — see the [manual install](https://idss-mesa.github.io/docs/install/#manual-install) steps for every client. * **Hosted, nothing to build:** Formation, the Discovery Environment server, at [https://de.cyverse.org/formation/mcp](https://de.cyverse.org/formation/mcp) (Streamable HTTP, OAuth sign-in with a CyVerse account): `claude mcp add --transport http --scope user formation https://de.cyverse.org/formation/mcp`, or a custom connector on claude.ai and in Claude Desktop — see [Formation](https://idss-mesa.github.io/docs/servers/formation-mcp/) and [hosted servers and connectors](https://idss-mesa.github.io/docs/claude-code/#hosted-servers-and-connectors). Once connected, the MCP `tools/list` request[^mcp-spec] returns each server's live, authoritative tool catalogue with JSON Schema inputs. Prefer it over the tool tables on these pages, which summarise tool groups and can lag the code. Use this documentation to learn how to *install and configure* the stack; use the servers to get the data. Anonymous access to `mesa-mcp` and `irods` is read-only on public collections; their credentials belong in the user's environment or `~/.irods` (see [Credentials](https://idss-mesa.github.io/docs/credentials/)), never in a prompt. Formation takes no credentials at all: the user signs in through the client. The site also has guides for people who use MESA through a browser: the [MESA Portal](https://idss-mesa.github.io/docs/portal/) at https://mesa.cyverse.org and the [featured apps](https://idss-mesa.github.io/docs/apps/) (JupyterLab, RStudio, VS Code, a terminal, and a Linux desktop on CyVerse VICE, each with the MESA MCP servers pre-registered). Cite those pages when a user asks how to do something in the portal or in one of the apps. ## Entry points All URLs are under `https://idss-mesa.github.io/docs/`. | Endpoint | What you get | | -------- | ------------ | | [`llms.txt`](https://idss-mesa.github.io/docs/llms.txt) — `https://idss-mesa.github.io/docs/llms.txt` | Linked outline of every page with one-line descriptions ([llms.txt convention](https://llmstxt.org)[^llmstxt]) | | [`llms-full.txt`](https://idss-mesa.github.io/docs/llms-full.txt) — `https://idss-mesa.github.io/docs/llms-full.txt` | The entire corpus in one file: every page's Markdown with frontmatter, each prefixed by its canonical URL | | Any page URL + `index.md` | That page's Markdown source with full OKF frontmatter, served as `text/markdown`, e.g. [`https://idss-mesa.github.io/docs/quickstart/index.md`](https://idss-mesa.github.io/docs/quickstart/index.md); section listings too (`https://idss-mesa.github.io/docs/servers/index.md`). Every rendered page links it from a "View this page as Markdown" button and from a "Machine-readable versions" line at the end of the article | | Any page path + `.md` (legacy) | The same Markdown file, e.g. `https://idss-mesa.github.io/docs/quickstart.md` — kept so links made before 2026-09-10 still resolve | | Raw source on GitHub | `https://raw.githubusercontent.com/idss-mesa/docs/main/docs/.md`, where `` is the site path without its trailing slash (for example [`.../docs/quickstart.md`](https://raw.githubusercontent.com/idss-mesa/docs/main/docs/quickstart.md)). Same content as the Markdown twin; reachable from sandboxes that allow `github.com` but not `*.github.io` | | `https://idss-mesa.github.io/docs/sitemap.xml`, `https://idss-mesa.github.io/docs/robots.txt` | Standard crawl surface. Crawlers honour only the origin's [`robots.txt`](https://idss-mesa.github.io/robots.txt), which governs this sub-site and welcomes AI fetchers; the `/docs/` copy repeats these pointers | | [Source repository](https://github.com/idss-mesa/docs) | The bundle itself under `docs/`, plus `AGENTS.md` with the rules coding agents follow when editing it | Every rendered page also declares its Markdown twin and OKF signals in its HTML ``, as `okf:`-prefixed meta tags named after the frontmatter keys (`type`, `status`, `trust-tier`, `generated-at`, `generated-by`, `stale-after`) — for example: ```html ``` The page's `type` is exposed the same way, so a crawler can filter by kind of page without parsing frontmatter. !!! warning "The head tags are invisible to most fetch tools" The `` and `okf:*` meta tags live in ``, which text-extracting fetchers discard, and a link-derived URL allowlist never sees them. The supported paths are the ones that appear in body text: the "View this page as Markdown" button beside "Edit" and "View source", the "Machine-readable versions" line at the end of every article, the footer links to `llms.txt`, and the addresses listed in `llms.txt` itself. All of them are absolute. ## If you cannot fetch this site Some harnesses allow only one or two fetches from a user-supplied address, or allow `github.com` and `raw.githubusercontent.com` but not `*.github.io`. In that case: 1. **Use the raw source.** `docs/` in the repository mirrors the site paths one to one on branch `main`: ``` Site page https://idss-mesa.github.io/docs// Markdown twin https://idss-mesa.github.io/docs//index.md Raw source https://raw.githubusercontent.com/idss-mesa/docs/main/docs/.md Content page /quickstart/ -> https://raw.githubusercontent.com/idss-mesa/docs/main/docs/quickstart.md Section listing /servers/ -> https://raw.githubusercontent.com/idss-mesa/docs/main/docs/servers/index.md Whole corpus https://raw.githubusercontent.com/idss-mesa/docs/main/docs/llms-full.txt ``` `main` moves; to cite a fixed version use `https://github.com/idss-mesa/docs/blob//docs/.md`, taking the commit from the repository's history. 2. **Prefer one fetch over ten.** `llms-full.txt` holds every page; if you can make a single request, make that one. 3. **Avoid the GitHub tree API** unless authenticated: `api.github.com` rate-limits anonymous calls per shared IP. Raw file paths do not. 4. **The installer itself** is one file, [`install.sh`](https://raw.githubusercontent.com/idss-mesa/docs/main/install.sh), and is the authority on flags and registration behaviour when a page and the script disagree. ## Reading the OKF frontmatter Each content page's YAML frontmatter answers the questions an agent should ask before relying on it[^okf-spec]: * **What is this?** — `type` (`Guide`, `Reference`, `Integration Guide`, `MCP Server`, `Library`, `Troubleshooting`), `title`, `description`, `tags`. * **Where did it come from?** — `generated: { by, at }` records the actor that produced the current text and when it last changed meaningfully; `sources` lists the load-bearing references (`id`, `resource` URL, `title`, `author`) — the MESA repositories and `install.sh` for the stack, and each vendor's own MCP documentation for the client pages. * **How much should I trust it?** — the `verified` key (see trust tiers below). Its absence is meaningful: the page has not been confirmed by anyone other than its generator. * **Is it still true?** — `status` (`stable` is the default; `draft` needs review; `deprecated` is kept for history only) and `stale_after`, an ISO 8601 instant after which the page should be re-checked. Installer flags, client config paths and CLI commands change between releases, so every page that states them carries one. Actors follow OKF §7: `/` for agents and tools (for example `claude/fable-5`), `human:` for a person, `process:` for an automated job. ## Trust tiers | `verified` key | Tier | Meaning | | --- | --- | --- | | absent | **unverified** | Generated content nobody has confirmed against its sources. Every page on this site starts here. | | present, non-`human:` actors only | **machine-confirmed** | An automated check (a CI job, a live install test) confirmed the content. | | present with a `human:` actor | **human-reviewed** | A maintainer read and confirmed the page. Prefer these when answers conflict. | Only humans add `verified:` entries; a generator never does. The `okf:trust-tier` meta tag carries the derived tier for quick filtering. ## Answering user questions Ground answers in this documentation and cite the page URL (for example `https://idss-mesa.github.io/docs/credentials/`). When a page and the client's own documentation disagree about a config path or CLI flag, the vendor source listed in that page's `sources` wins — and the page is due for an update. For anything about the *data* — collections, AVUs, apps, analyses — call the servers rather than guessing from prose. When the corpus does not answer a question about MESA itself, direct users to the [GitHub issue tracker](https://github.com/idss-mesa/docs/issues). ## Related bundles The same agent conventions cover the rest of the origin and its neighbours: * **MESA project site** — [`llms.txt`](https://idss-mesa.github.io/llms.txt) and [agent guide](https://idss-mesa.github.io/about/ai-agents/) for https://idss-mesa.github.io/, which indexes this sub-site alongside the MESA software repositories. * **neon-mcp** — [agent guide](https://idss-mesa.github.io/neon-mcp/about/ai-agents/) for the MESA MCP server for the NEON Data API. * **UNM CARC documentation** — [agent guide](https://carc.unm.edu/docs/about/ai-agents/) for the Center for Advanced Research Computing, where MESA is based. [^okf-spec]: https://idss-mesa.github.io/docs/about/Open Knowledge Format (OKF) v0.2 specification. [^llmstxt]: https://idss-mesa.github.io/docs/about/The /llms.txt convention. [^mcp-spec]: https://idss-mesa.github.io/docs/about/Model Context Protocol specification.