Vaglio is an academic research governance server that helps you find, read, appraise, and archive scholarly works with built-in rate-limit protection across a fleet of agents.
Search (vaglio_search): Find works across Crossref, OpenAlex, PubMed, and OpenAIRE with automatic failover — rate‑limited sources are skipped, and refusals are reported.
Read (vaglio_read): Retrieve and store full text from arXiv, Europe PMC, or Unpaywall; read depth is derived from actual stored files, not just declarations.
Status (vaglio_status): Monitor shared request budgets fleet‑wide, showing which hosts are in cooldown.
Catalogue (vaglio_sources): List available sources, their roles (FIND/OPEN/READ), and full‑text capabilities.
Appraise (vaglio_appraise): Assign an evidence tier (A–D) to a claim — Tier A requires at least an abstract, Tier D requires a recorded refusal reason.
Archive (vaglio_inscribe): Save a research run as a versioned, schema‑valid record in ~/ricerche, including full‑text copies and index regeneration; refuses to record falsified claims as durable verdicts.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@vaglio-mcp search for papers on CRISPR gene editing"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server per la ricerca accademica governata. Vagliare: separare il grano dalla pula. Trova, apre, legge — e non mente mai su quale delle tre è successa.
Nasce da un incidente misurato il 2026-07-28: nove agent di ricerca in parallelo
hanno fatto scattare il rate-limit di OpenAlex per 18 ore (Retry-After: 64902) a metà di un workflow. Ogni agent si comportava bene da solo; insieme
erano un attacco. Il backoff per-chiamata non protegge da questo, perché il
budget appartiene alla flotta, non al chiamante.
Ricerca completa: ~/ricerche/topics/metodo-ricerca-accademica/pipeline-fonti-open-access/.
Il prior art esiste ed è buono — openags/paper-search-mcp
(MIT, 20 fonti, backoff, catena OA-first) copre la meccanica delle fonti. Vaglio
non la riscrive: aggiunge i tre organi che mancano.
Organo | Cosa fa |
Governance | token bucket condiviso fra processi ( |
Evidenza |
|
Inscrizione | il run diventa un record versionato in |
Related MCP server: wikipedia-recent-changes-mcp
Europe PMC e PubMed pubblicano il tipo MeSH di ogni lavoro, e Crossref marca
i preprint come posted-content. Sono dati della fonte, non giudizi — quindi il
tetto di forza di un claim si legge, non si opina:
Il record dice | Classe | Tier massimo |
| primary-trial | A |
| synthesis | A |
| secondary | B |
| preprint (non peer-reviewed) | B |
| primary-study | nessun tetto |
niente | unknown | nessun tetto |
Su una ricerca reale (binaural beats anxiety, Europe PMC) la separazione è
netta al primo colpo: un solo RCT ammette tier A, mentre una Letter, una Review
e un Case Report si fermano a B. Chi volesse scrivere "tier A: i binaural beats
riducono l'ansia" citando la review viene fermato dal costruttore, non da un
revisore a valle.
Due precisazioni, perché il meccanismo sia onesto: il tetto non promuove mai nulla — un claim debole su un RCT resta debole; e quando la fonte non dichiara il tipo, non c'è tetto e il giudizio dell'agent vale come prima.
I ruoli non sono intercambiabili — è questo che fa funzionare il failover.
Ruolo | Fonti | Nota |
FIND | Crossref → OpenAlex → PubMed → OpenAIRE | Crossref è la spina dorsale: 3 req/s, |
OPEN | Unpaywall | dal DOI alla copia open access legale |
READ | arXiv, Europe PMC, CORE | arXiv per fisica/matematica/DSP; Europe PMC dà il full text XML senza chiave, ed è dove si leggono i metodi |
Su 429 non si ritenta la stessa fonte: si cambia fonte per lo stesso scopo.
Ritentare un host che ha risposto con 18 ore di Retry-After è tempo buttato.
Fuori per scelta: Sci-Hub (esposizione legale che un portfolio commerciale non può portare) e i riassuntori mediati da LLM (Elicit, Consensus, SciSpace: mettono un secondo grado di separazione fra claim e fonte primaria).
Tool | Cosa fa |
| cerca con failover per ruolo; riporta quali fonti hanno rifiutato e perché |
| scarica e archivia il corpo, rendendo verificabile la profondità |
| vista di flotta: chi è utilizzabile, chi è in cooldown e per quante ore |
| catalogo fonti, ruoli, capacità di full text |
| assegna un tier a un claim, sotto la disciplina che lo guarda |
| scrive il record in |
cd ~/mcp/vaglio-mcp
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest # i falsificatoriRegistrazione come server MCP:
claude mcp add vaglio -- ~/mcp/vaglio-mcp/.venv/bin/vaglio-mcpNessuna chiave, nessun account, nessuna dipendenza HTTP di terze parti: il
trasporto è urllib di stdlib, di proposito — questo strato non può avere una
dipendenza che decida di fare una richiesta scavalcando il throttle.
I test sono i falsificatori pre-registrati nel record di ricerca, non un contorno:
F1 — il budget è condiviso: due istanze indipendenti (due processi) non
ottengono rate token a testa; un 429 su una è visibile all'altra senza che
abbia mai chiamato; un 429 senza Retry-After non vale mai zero.
F2 — la profondità non mente: file vuoto ≠ full-text; tier A su soli metadata è rifiutato; tier D senza motivazione è rifiutato; un run letto perlopiù ad abstract lo dichiara.
F3 — il failover cambia fonte: l'host bloccato è provato una volta sola, mai ritentato; se cadono tutte, il risultato vuoto si spiega invece di sembrare "nessun risultato".
F4 — l'inscrizione è valida: frontmatter conforme allo schema
dell'archivio, slug in kebab-case, full text copiato in sources/.
F5 — il tetto derivato regge: le etichette reali delle API mappano alla classe giusta; una review rifiuta il tier A e accetta il B; un RCT ammette A; un preprint è segnalato come non peer-reviewed e limitato; il silenzio della fonte non declassa nulla; il tetto non promuove mai un claim debole.
Con una regola in più, di governo e non di codice: vaglio_inscribe rifiuta
status: falsified. Dire in conversazione che qualcosa non regge è dovuto;
inscriverlo nel record come verdetto chiuso è una decisione di chi possiede la
ricerca, non dello strumento.
I due organi centrali sono agnostici rispetto alla ricerca accademica e si usano senza toccare l'MCP: servono a qualunque flotta di agent.
pip install "vaglio-mcp @ git+https://github.com/Alemusica/vaglio-mcp"Governance — qualunque API con rate limit, condivisa fra processi:
from vaglio_mcp.core.throttle import Throttle, HostBlocked
t = Throttle() # stato condiviso in ~/.vaglio/throttle
try:
t.acquire("api.example.com") # attende il turno, nel budget della flotta
except HostBlocked as e:
... # l'host e fuori per e.seconds_left: cambia strada
t.report_rate_limited("api.example.com", retry_after=3600) # lo dice a tuttiEvidenza — tier e profondita di lettura, per ricerca ma anche per due diligence, FTO, audit normativo:
from vaglio_mcp.core.evidence import Finding, Paper, Tier
Finding(claim="...", tier=Tier.A, paper=Paper(title="...", source="..."))
# TierDiscipline: tier A dichiarato su soli metadata viene rifiutato qui,
# non scoperto a valle.Nessuno dei due importa l'altro, e nessuno dei due sa cosa sia un paper: il throttle conosce host e secondi, l'evidenza conosce claim e artefatti.
Versione 0.2.0.
Candidati all'estrazione verso magazzino (dichiarati, non ancora promossi —
regola dei 3 consumatori): core/throttle.py come primitivo di governance
riusabile da qualunque flotta di agent, e core/evidence.py come disciplina
tier/profondità agnostica rispetto al dominio.
Attach an evidence tier to a claim, under the discipline that guards it.
Tier A requires at least the abstract to have been retrieved — asserting
RCT-strength from a title alone is rejected here rather than caught later.
Tier D is a RECORDED refusal: it demands refused_reason, so a rejected
idea leaves a trace instead of vanishing.
| Name | Required | Description | Default |
|---|---|---|---|
| doi | No | ||
| tier | Yes | ||
| claim | Yes | ||
| abstract | No | ||
| transfer | No | ||
| mechanism | No | ||
| paper_title | Yes | ||
| fulltext_path | No | ||
| refused_reason | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses that Tier D leaves a trace (refused_reason) and that Tier A requires abstract. However, does not explain if the tool is idempotent, destructive, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured with line breaks. Every sentence adds value. Not excessively verbose, though could be slightly more compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters (3 required), no output schema, and no annotations, the description covers high-level behavior but lacks detail on many parameters and return value. Incomplete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only explains abstract and refused_reason semantics. With 0% schema coverage, few parameters (doi, transfer, mechanism, fulltext_path) are left unexplained. Description does not compensate for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool attaches an evidence tier to a claim, with specific context for Tier A and Tier D. Distinguishes from siblings implicitly through action (appraise vs search/read/status/sources/inscribe).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on when to use Tier A (abstract required) and Tier D (requires refused_reason). Does not compare to sibling tools, but the difference in action is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write the run into the ~/ricerche archive as a versioned, schema-valid record.
Closes the loop the archive exists for: research that stays in a transcript
gets lost. Copies any stored full text into the record's sources/ and
regenerates the index.
Will REFUSE status: falsified — declaring something dead in a durable
artifact is the research owner's decision, not the tool's.
| Name | Required | Description | Default |
|---|---|---|---|
| kin | No | ||
| body | Yes | ||
| tier | No | ||
| title | Yes | ||
| topic | Yes | ||
| method | No | ||
| status | No | open | |
| session | No | ||
| version | No | 0.1.0 | |
| record_id | Yes | ||
| disclosure | No | LOCAL |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: copies full text, regenerates index, and refuses status='falsified'. It does not cover all aspects (e.g., error handling, idempotency) but is notably transparent about side effects and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is five sentences, each adding value: core action, context, side effects, refusal rule. No redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters, no annotations, and no output schema, the description is insufficient. It explains the main function and a key constraint, but the bulk of parameters are unelaborated, leaving agents to infer meaning.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description only mentions the 'status' parameter (via refusal) and implicitly 'body' (as full text). The other 9 parameters (kin, tier, method, session, disclosure, etc.) remain unexplained, providing minimal semantic help.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'write' and the resource 'archive as a versioned, schema-valid record'. It distinguishes from siblings (search, read, status, sources, appraise) by detailing the inscribing action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finalizing a run into the archive ('closes the loop'), but lacks explicit when-to-use vs alternatives or when-not-to-use. No direct comparison to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve and STORE the body of a work, so its depth becomes verifiable.
Tries the native readers first (arXiv PDF, Europe PMC full-text XML), then
resolves the DOI through Unpaywall to a legal open-access copy. The stored
file is the proof: read_depth reports full-text only when bytes exist on
disk. Returns metadata-only depth without complaint when no OA copy exists —
that is an honest outcome, not a failure.
| Name | Required | Description | Default |
|---|---|---|---|
| doi | No | ||
| pmcid | No | ||
| title | Yes | ||
| oa_url | No | ||
| source | No | crossref | |
| arxiv_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully bears the burden of behavioral disclosure. It explains the retrieval strategy (native readers then Unpaywall), storage behavior, the 'read_depth' reporting logic, and the honest failure mode (returns metadata-only depth). It adds valuable transparency beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: first states the core purpose, second outlines the process, third clarifies the outcome. Every sentence adds value, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (6 parameters, no output schema, no annotations), the description adequately covers workflow and behavior but lacks parameter details and return value structure. It is minimally complete for an agent to understand the tool's main function but incomplete for correct parameter usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning no parameter descriptions exist in the schema. The description does not explain any of the 6 parameters (doi, pmcid, title, oa_url, source, arxiv_id), leaving the agent without necessary context for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves and stores the body of a work, with a specific verb-resource pair. It distinguishes from sibling tools (search, status, sources, appraise, inscribe) by focusing on full-text retrieval and storage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when full-text retrieval is needed, but does not explicitly state when to use or not use this tool versus alternatives. It provides context of the fallback process but lacks clear exclusions or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find works across the open bibliographic sources, with failover by role.
Walks Crossref -> OpenAlex -> PubMed -> OpenAIRE until one answers. A source that is rate limited is skipped, not retried: the response reports which sources refused and why, so a thin result is visibly thin.
Args: query: search terms. limit: max results (keep modest; the budget is shared across agents). prefer: force a source to the front, e.g. "pubmed" for biomedical work.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| prefer | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses failover across sources, rate limit skipping, and response reporting of refusals. It does not mention destructive behavior (none expected) or return format, but the core behavior is well explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two short paragraphs plus an Args list. The first sentence front-loads the purpose, and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers the failover and response reporting. However, it could specify the return value structure (e.g., list of works) for full completeness. Still, it provides essential context for an agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explicitly documents all three parameters: query (search terms), limit (max results with budget hint), and prefer (force source). This adds significant meaning beyond the raw schema, making the tool usable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Find works across the open bibliographic sources,' specifying the verb 'find' and the resource 'works'. It also mentions the failover behavior, distinguishing it from sibling tools like vaglio_read or vaglio_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the failover behavior and the optional prefer parameter, implying when to use it (searching across multiple sources). However, it does not explicitly mention when not to use this tool or provide direct comparisons to sibling tools, leaving usage guidance mostly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Catalogue of sources and what each one is actually good for.
Roles are not interchangeable: finders locate a DOI, the opener resolves it to a legal copy, readers give you the body. Picking by role is what makes failover work.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It describes the conceptual behavior (roles and failover) but does not disclose operational traits like read-only nature, external calls, or safety. For a simple catalogue tool, this is adequate but could be more explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact with two short paragraphs. The first sentence is front-loaded with purpose. Every sentence adds unique information (catalogue, role explanation, failover). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description adequately conveys the tool's value and output concept. It lacks explicit mention of output format (list, dictionary) but the role context is sufficient for an agent to infer usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so schema coverage is 100%. The description adds value beyond the schema by explaining the output structure (roles). Baseline for 0 params is 4, but the role explanation justifies a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is a 'catalogue of sources' explaining what each is good for, with specific roles like finders, opener, readers. This verb-resource combination is precise and distinguishes it from siblings which likely handle different actions (search, read, etc.).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that roles are not interchangeable and selecting by role makes failover work, implying the tool helps choose the right source for a task. However, it lacks explicit instructions on when to use this tool versus siblings, and no negative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the shared request budget: which hosts are usable, which are cooling down.
This is the fleet view. When a source shows blocked_hours, every agent in
every process is blocked on it — switch source instead of waiting.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the tool is read-only (show), explains the meaning of output fields (blocked_hours), and implies no destructive behavior. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded purpose, no extraneous information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple status tool with no output schema, the description adequately covers return concepts (usable hosts, cooling down, blocked_hours). No missing critical details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so description is not required to add parameter info. The baseline is 4 for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it shows the shared request budget and fleet view of usable/cooling down hosts, with a specific verb 'show' and resource. It distinguishes from sibling tools which are search, read, sources, appraise, inscribe.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context about when to use (to check budget) and gives actionable advice ('switch source instead of waiting') when blocked_hours appears. Lacks explicit exclusions but covers key usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0vaglio_appraisevaglio_inscribevaglio_readvaglio_searchvaglio_sourcesvaglio_statusScored across 6 tools
Each tool has a clearly distinct purpose: vaglio_search finds works, vaglio_read retrieves full text, vaglio_status shows budget/blocked hosts, vaglio_sources catalogues sources, vaglio_appraise attaches evidence tiers, vaglio_inscribe archives runs. No ambiguity.
All tool names follow a consistent 'vaglio_<verb>' pattern with lowercase and underscores. Verbs are descriptive and match the action (search, read, status, sources, appraise, inscribe).
Six tools is well-scoped for the server's purpose of searching, reading, appraising, and archiving bibliographic works. Each tool earns its place without unnecessary overlap.
The tool set covers the full logical workflow: search, retrieve full text, check system status, list sources, appraise evidence, and archive results. No obvious gaps for the intended domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
An MCP server for deep research or task groups
Independent trust scores, tool surfaces and change history for MCP servers.
Hosted MCP server for finding authoritative primary data sources and official portals.