Allows querying the NIAID Data Ecosystem using Elasticsearch query syntax, supporting field-specific queries, aggregations, pagination, and sorting.
Click on "Deploy 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., "@niaid-data-mcp-server search for COVID-19 datasets"
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.
An MCP (Model Context Protocol) server for the NIAID Data Ecosystem API, enabling LLMs to search biomedical research resources — datasets, clinical studies, publications, repositories, and more — funded or supported by NIAID.
niaid_data_querySearch the NIAID Data Ecosystem using Elasticsearch query string syntax.
Parameters:
Parameter | Type | Default | Description |
| string |
| Elasticsearch query string. Supports field-specific queries, boolean operators, and wildcards. |
| int | 10 | Number of results to return (1–1000). |
| int | 0 | Number of results to skip (for pagination). |
| string | — | Sort field; prefix with |
| string | — | Comma-separated fields to return (e.g., |
| list[string] | — | Fields to aggregate/facet by (e.g., |
| int | 10 | Max aggregation buckets per field (1–1000). |
| bool | — | Include relevance score explanation. |
| string |
|
|
Example queries:
q="COVID-19 AND @type:Dataset" — find COVID-19 datasets
q="*", aggs=["@type"] — summarize resource types across the whole catalog
q="malaria", sort="-date", size=20 — most recent malaria resources
Related MCP server: data-aggregator-mcp
Requires Python 3.11+ and uv.
uv syncuv run python main.pyClaude Desktop config (claude_desktop_config.json):
{
"mcpServers": {
"niaid-data": {
"command": "uv",
"args": ["run", "python", "main.py"],
"cwd": "/path/to/niaid-data-mcp-server"
}
}
}PORT=8000 uv run python main.pyA /health endpoint is available at http://localhost:8000/health.
Fetch the complete record for a single NIAID Data Ecosystem resource by its ID.
Retrieves all available fields for a specific resource using its unique identifier. Use this after niaid_data_query to get the full details of a record of interest.
Args: params (GetInput): Validated input parameters containing: - id (str): Unique record identifier from the '_id' field of query results (e.g., 'dde_373d5e89c734f65e'). - response_format (ResponseFormat): 'json' (default) for the complete raw record, or 'markdown' for a human-readable summary.
Returns: str: The complete record data.
JSON response: Full record object as returned by the API, including all
available fields (name, description, author, date, url, conditionsOfAccess,
measurementTechnique, species, funding, citation, etc.).
Markdown response: Formatted summary with key fields highlighted.
Error responses:
- "Error: Record not found for ID '...'" if the ID does not exist
- "Error: <message>" for API or network failuresExamples: - Use when: "Get full details for dataset dde_373d5e89c734f65e" -> params with id='dde_373d5e89c734f65e' - Use when: After a query returns results and you need all fields for one record -> params with id=<_id from query hit>, response_format='json'
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes | Input model for fetching a single NIAID Data record by ID. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining the two response formats (json and markdown), the complete set of fields returned, and the specific error messages for not-found and API failures. This goes beyond annotation-only information, though it does not disclose potential performance or authentication nuances.
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 well-organized into clear sections: a one-sentence overview, args, returns, error responses, and examples. It is front-loaded with the purpose and every section adds practical value. No wasted words or redundant repetition of schema or annotations.
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 relative simplicity of the tool, the description covers all necessary context: what the tool does, when to use it in the broader workflow, parameter usage, return format details, error behaviors, and concrete examples. With an output schema implied and annotations present, no further details are needed.
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?
Although the schema already describes both parameters at 100% coverage, the description significantly enriches them. It clarifies that the id comes from the '_id' field of query results and provides a concrete example. It also explains the difference between 'json' and 'markdown' response formats and their defaults, adding meaning beyond the raw schema.
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 opens with 'Fetch the complete record for a single NIAID Data Ecosystem resource by its ID', a specific verb+resource+method statement. It further distinguishes itself from siblings by explicitly noting 'Use this after niaid_data_query to get the full details of a record of interest.'
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?
Clear guidance is provided: 'Use this after niaid_data_query to get the full details of a record of interest.' This names the alternative query tool and indicates the workflow. Examples also show exactly when to use the tool, satisfying the explicit 'when' and 'alternative' requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the NIAID Data Ecosystem for biomedical research resources.
Queries the NIAID Data Ecosystem API (https://data.niaid.nih.gov), which indexes datasets, clinical studies, publications, and other research resources related to infectious and immune-mediated diseases funded or supported by NIAID.
Supports Elasticsearch query string syntax for powerful full-text and field-specific searches. Results include datasets, clinical trials, repositories, computational tools, and more.
Args: params (QueryInput): Validated input parameters containing: - q (str): Elasticsearch query string. Use '' for all records. Supports field-specific syntax: 'name:COVID', 'author.name:Smith', '@type:Dataset', 'conditionsOfAccess:Open'. Default: ''. - size (Optional[int]): Number of results per page (1-1000). Default: 10. - offset (Optional[int]): Results to skip for pagination. Default: 0. - sort (Optional[str]): Sort field; prefix with '-' for descending (e.g., '-date'). Default: relevance score. - fields (Optional[str]): Comma-separated fields to return (e.g., 'name,description,@type,date'). Returns all fields if omitted. - aggs (Optional[List[str]]): Fields to aggregate/facet by (e.g., ['@type', 'conditionsOfAccess']). Useful for summarizing result distributions without reading each record. - facet_size (Optional[int]): Max aggregation buckets per field. Default: 10. - explain (Optional[bool]): Include relevance score explanation. - response_format (ResponseFormat): 'markdown' (default) for readable summaries or 'json' for complete structured data.
Returns: str: Formatted search results.
Markdown response includes:
- Total result count and pagination info
- For each hit: name, type, ID, score, description (truncated), URL, date
- Aggregation summaries (if aggs requested)
JSON response schema:
{
"total": int, # Total matching records
"count": int, # Records in this response
"offset": int, # Current pagination offset
"has_more": bool, # Whether more results are available
"next_offset": int | null, # Offset for next page
"took_ms": int, # Query time in milliseconds
"hits": [...], # Full record objects from the API
"aggregations": {...} # Aggregation buckets (if requested)
}
Error response: "Error: <message with suggested fix>"Examples: - Use when: "Find open-access COVID-19 datasets" -> params with q='COVID-19 AND @type:Dataset AND conditionsOfAccess:Open' - Use when: "What types of resources are available?" -> params with q='*', aggs=['@type'], size=0 - Use when: "Find datasets with access conditions distribution" -> params with q='@type:Dataset', aggs=['conditionsOfAccess'], size=5 - Use when: "Search for malaria resources sorted by date" -> params with q='malaria', sort='-date', size=20 - Use when: "Page through results" (after first call with offset=0, size=10) -> params with same q, offset=10, size=10
Error Handling: - Returns "Error: Invalid query (HTTP 400)..." if query syntax is invalid - Returns "Error: Rate limit exceeded (HTTP 429)..." if too many requests - Returns "Error: Request timed out..." if query is too broad/slow
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes | Input model for the NIAID Data query operation. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only, idempotent, and non-destructive. The description adds substantial behavioral context: it calls an external API with rate limiting and timeout errors, returns formatted output (markdown or JSON), and includes pagination and aggregation details beyond the annotation hints.
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 long but well-organized into Purpose, API context, Args, Returns, Examples, and Error Handling. It front-loads the core purpose in the first sentence, and every section adds operational 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?
The description includes the full JSON response schema, markdown output structure, error handling, and multiple examples. Even with the output schema present, it explains expected behaviors thoroughly, making it complete for a complex query 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?
Schema coverage is 100%, but the description's Args section goes beyond the schema by adding Elasticsearch syntax examples ('name:COVID', '@type:Dataset'), explaining how 'offset' and 'size' work together for pagination, and clarifying that 'size=0' can be used with aggregations. The examples show concrete parameter combinations.
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 opens with 'Search the NIAID Data Ecosystem for biomedical research resources,' clearly stating the verb and resource. It further explains it queries the API and supports Elasticsearch syntax, but it does not explicitly contrast with sibling tools like niaid_data_get or niaid_data_summarize.
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 'Examples' section provides multiple 'Use when:' scenarios, giving explicit context for when to invoke the tool, such as 'Find open-access COVID-19 datasets' and 'What types of resources are available?'. However, it does not mention when not to use it or suggest alternatives for single-record retrieval or other sibling operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize a NIAID Data search without returning all records to the context.
Use this tool BEFORE niaid_data_query when a search may return many results, or when you need to understand what's available before fetching full records. Returns a compact overview: total count, distribution breakdowns across key fields, a small sample of top hits, and specific suggestions for narrowing the search.
This is the right tool when:
You don't know how many results a query will return
The user asks "what's available about X" or "give me an overview of X"
A previous niaid_data_query returned 1000+ hits
You need to help the user decide how to filter or focus their search
Args: params (SummarizeInput): Validated input parameters containing: - q (str): Elasticsearch query string (same syntax as niaid_data_query). Use '' to summarize the entire catalog. Default: ''. - sample_size (Optional[int]): Top-scoring records to show as examples (1–20). Does NOT return all results. Default: 5.
Returns: str: Markdown summary containing:
**Overview**
- Total matching records and query time
**Distribution** (fields with data only)
- Resource type breakdown (Dataset, ComputationalTool, ResourceCatalog, …)
- Access conditions (Open, Restricted, Closed)
- Health conditions, infectious agents, species, measurement techniques,
topic categories, funders — wherever data exists for this query
**Sample records** (top `sample_size` hits by relevance)
- Name, type, ID, and description snippet for each
**Refinement suggestions**
Generated from the actual distribution data:
- Concrete filter additions (e.g., `AND @type:Dataset`)
- Field-specific search tips
- Pagination guidance if proceeding with niaid_data_queryExamples: - Use when: "What COVID-19 resources are available?" -> params with q='COVID-19' - Use when: A query just returned 48,000 results -> params with q= to understand how to narrow it - Use when: "Give me an overview of malaria datasets" -> params with q='malaria' - Don't use when: You need specific records (use niaid_data_query instead) - Don't use when: You have a specific ID (use niaid_data_get instead)
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes | Input model for summarizing a potentially large set of NIAID Data results. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although annotations already declare readOnlyHint, openWorldHint, and idempotentHint, the description adds meaningful behavioral context beyond them: it does NOT return all records, returns a compact overview, limits sample records to sample_size, and has no side effects. No contradiction exists between annotations and description.
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 long but extremely well-structured with clear sections: overview, when to use, args, returns, and examples. It is front-loaded with the core purpose, and every section adds actionable information without filler.
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?
The description is fully self-contained: it explains the tool's exact output structure, parameter behavior, examples, and exclusions. Given the tool's moderate complexity and rich input schema, this description provides complete guidance for an agent to select and invoke it correctly.
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?
The input schema already covers both parameters with detailed descriptions, giving a strong baseline. The tool description reinforces key semantics ('same syntax as niaid_data_query', 'Use * for the entire catalog', 'Does NOT return all results') and adds practical examples, though much of this duplicates the schema text.
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 opens with a specific action and resource: 'Summarize a NIAID Data search without returning all records to the context.' It clearly distinguishes this from the sibling tools niaid_data_query and niaid_data_get by stating it provides an overview rather than full records.
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 provides explicit when-to-use guidance with a bulleted list ('Use this tool BEFORE niaid_data_query when a search may return many results') and explicit when-not-to-use guidance ('Don't use when: You need specific records (use niaid_data_query instead)'). This fully clarifies tool selection versus alternatives.
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.0niaid_data_getniaid_data_queryniaid_data_summarizeScored across 3 tools
Each tool has a clearly distinct purpose: query for searching with pagination, get for retrieving a single record by ID, and summarize for overview and refinement suggestions. No overlapping functionality.
All tools follow the consistent pattern 'niaid_data_<verb>' with lowercase snake_case verbs (query, get, summarize). The naming convention is uniform and predictable.
Three tools is well-scoped for a read-only data search server. Each tool serves a necessary, non-redundant function, and the count is within the ideal range for a single API integration.
The tool set covers the complete user workflow: summarize to explore and narrow a search, query to retrieve paginated hits, and get to fetch full details for a specific record. No obvious gaps in the search-and-retrieve lifecycle.
Search public Australian environmental evidence with provenance across authoritative catalogues.
Scholarly search: OpenAlex, Crossref, arXiv, OpenCitations and PubMed in one endpoint.
Search 36M+ PubMed biomedical articles and ClinicalTrials.gov studies.
Multi-engine scholarly research server for search, traversal, full text, and reading lists.
