cern-opendata-mcp-server

List CERN Open Data Record Files

cern_opendata_list_files

Read-onlyIdempotent

List one record's files: its file indexes (groups of up to ~1,500 files) with their XRootD URI-list URLs, and per file the XRootD URI, HTTPS download URL, size, adler32 checksum and availability. Without index, returns the record's indexes and its regular files; with index, reads only that index and pages through its files. Files marked on demand sit on tape and must be requested on the record's portal page before download.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "recid": "<recid>"
    },
    "name": "cern_opendata_list_files"
  }
}

Input Schema

Name	Required	Description
`index`	No	A file index key from the indexes list, matched exactly (a .txt ending is read as .json). Omit to list the record's indexes and regular files.
`limit`	No	Files per page, 1-500. A value above 500 is served at 500.
`recid`	Yes	Record id: up to 12 digits (6004), optionally after a lowercase experiment prefix (atlas-160006). cern_opendata_search_records and cern_opendata_get_records return it.
`cursor`	No	next_cursor from the previous page, unchanged, with the same recid and index. Omit for the first page.

Output Schema

Name	Required	Description
`cap`	No	The page size (limit) applied to this call.
`error`	No	Present when the call failed. Absent on success.
`files`	No	This page: regular files in record scope, index files in index scope.
`recid`	No	The record id.
`scope`	No	record: the record's indexes and regular files; index: one index's files.
`shown`	No	Number of items returned on this page.
`title`	No	Record title.
`notice`	No	Continuation, empty-result guidance or result caveats; absent when none.
`indexes`	No	Every file index in record scope; only the selected one in index scope.
`children`	No	Child recids of a fileless umbrella record; empty otherwise.
`has_more`	No	True when more files remain past this page.
`truncated`	No	True when more results remain past this page; notice says how to reach them.
`portal_url`	No	The record page, where on-demand (tape) files are requested.
`totalCount`	No	Files in scope: regular files in record scope, index files in index scope.
`next_cursor`	No	Pass as cursor, with the same recid and index, for the next page.
`availability`	No	Record-level availability: online, partial, ondemand or requested.
`availability_details`	No	File counts by availability state for the whole record.

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedOct 30, 2026

changedOutput schema / properties / children / description

Previous value: -"Set only for an umbrella record holding no files itself: the child recids whose files make it up. Empty otherwise."New value: +"Child recids of a fileless umbrella record; empty otherwise."

changedOutput schema / properties / files / description

Previous value: -"This page of files: regular files in record scope, the index's files in index scope."New value: +"This page: regular files in record scope, index files in index scope."

changedOutput schema / properties / files / items / properties / key / description

Previous value: -"File key as the portal states it; index members read <index>.json_<n>. Absent when the portal lists the file without one; filename then names it."New value: +"Portal file key; index members use <index>.json_<n>. Absent for keyless files, named by filename instead."

changedOutput schema / properties / indexes / items / properties / availability / description

Previous value: -"File counts by availability state, as the portal states them; empty ({}) when it states none."New value: +"Portal availability counts; {} when unstated."

changedOutput schema / properties / indexes / items / properties / key / description

Previous value: -"Index key (…_file_index.json, or a name such as training_files.json); pass it as index to page its files."New value: +"Index key (…_file_index.json, training_files.json, etc.); pass as index to page its files."

changedOutput schema / properties / indexes / items / properties / number_files / description

Previous value: -"Files in the index, as the portal states it, else the count of the files the index lists."New value: +"Portal file count, else count of listed index files."

changedOutput schema / properties / indexes / items / properties / size_in_bytes / description

Previous value: -"Total size of the index files in bytes, as the portal states it, else the sum of the listed files' sizes."New value: +"Index size in bytes: portal total, else sum of listed file sizes."

changedOutput schema / properties / notice / description

Previous value: -"Guidance for the next call: how to page on, why nothing matched and what to change, or a caveat about the results."New value: +"Continuation, empty-result guidance or result caveats; absent when none."

Changed3 schema fields changedOct 18, 2026

changedInput schema / properties / limit / description

Previous value: -"Files per page, 1-500."New value: +"Files per page, 1-500. A value above 500 is served at 500."

changedInput schema / properties / limit / maximum
```
Previous value: -500New value: +10000
```

changedInput schema / properties / recid / description

Previous value: -"Record id: up to 12 digits (6004), optionally after an experiment prefix (atlas-160006); recid:6004 or a portal record URL also work. cern_opendata_search_records and cern_opendata_get_records return it."New value: +"Record id: up to 12 digits (6004), optionally after a lowercase experiment prefix (atlas-160006). cern_opendata_search_records and cern_opendata_get_records return it."

First observedOct 2, 2026

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent, so the burden is lower, yet the description adds real value: pagination semantics, the ~1,500-file index grouping, and the crucial caveat that on-demand files sit on tape and must be requested on the portal before download. It does not state error behavior or whether missing/unavailable files cause failures.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, front-loaded with what is listed and immediately followed by the with/without-index branch and the tape caveat. Dense but nearly every clause carries a distinct fact; only the per-file field enumeration slightly duplicates the output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values needn't be re-explained, yet the description is still complete on the things that matter: paging contract, index vs. no-index behavior, and the tape-request prerequisite. A note on what happens with an invalid index or empty results is the only gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds only modest meaning beyond the schema, namely the relationship between index and paging, while the .txt/.json matching detail and the limit cap live in the schema itself.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List one record's files') and enumerates exactly what is returned: file indexes with XRootD URI-list URLs, plus per-file URI, HTTPS URL, size, checksum and availability. This clearly separates it from the record-metadata siblings, but it never names or contrasts an alternative tool explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit branching conditions: omit index to get indexes and regular files, supply index to read and page through that index's files, and use cursor for subsequent pages. It also flags the on-demand/tape case that requires a separate portal request before download. It stops short of naming when to call a sibling instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All cern-opendata-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.