# `pubmed__pubmed_search_articles`

**Pubmed Search Articles**

Search PubMed with full query syntax, filters, and date ranges. Returns PMIDs and optional brief summaries. Supports field-specific filters (author, journal, MeSH terms), common filters (language, species, free full text), and pagination via offset for paging through large result sets.

- Server: [PubMed](https://gateway.mcpharbor.dev/docs/servers/pubmed) (`dev.mcpharbor.gateway/pubmed`)
- Price per call: $0.0001 (100 micro-USD); only tools/call is charged
- Endpoint: `https://gateway.mcpharbor.dev/mcp` or `https://gateway.mcpharbor.dev/mcp/pubmed`
- Upstream tool: exposed by the provider; called through this gateway as `pubmed__pubmed_search_articles`
- Provider terms: <https://www.ncbi.nlm.nih.gov/books/NBK25497/> (verified 2026-09-19)
- Upstream API documentation: <https://www.ncbi.nlm.nih.gov/books/NBK25497/>
- Rate limit: 150 requests per minute
- Attribution required: NCBI's Disclaimer and Copyright notice must be evident to users of your product

## Parameters

- `author` (string, optional): Filter by author name (e.g. "Smith J")
- `dateRange` (object, optional): Filter by date range. The filter is applied only when both \`minDate\` and \`maxDate\` are non-empty; either one empty disables the entire date range.
- `freeFullText` (boolean, optional): Only include free full text articles
- `hasAbstract` (boolean, optional): Only include articles with abstracts
- `journal` (string, optional): Filter by journal name
- `language` (string, optional): Filter by language (e.g. "english")
- `maxResults` (integer, optional): Maximum results to return Default: `20`.
- `meshTerms` (array, optional): Filter by MeSH terms. Multiple terms are AND'd — all must match.
- `offset` (integer, optional): Result offset for pagination (0-based). PubMed serves at most the first 9999 records of a result set, so this caps at 9998; narrow the query or add filters to reach anything beyond it. Default: `0`.
- `publicationTypes` (array, optional): Filter by publication type (e.g. "Review", "Clinical Trial", "Meta-Analysis"). Multiple values are OR'd — any match qualifies.
- `query` (string, required): PubMed search query (supports full NCBI syntax). Must carry a search term: a value that is blank once markup is stripped is rejected rather than sent to PubMed as an empty term.
- `sort` (string, optional): Sort order: relevance (default), pub_date (newest first), author, or journal One of: `relevance`, `pub_date`, `author`, `journal`. Default: `relevance`.
- `species` (string, optional): Filter by species One of: `humans`, `animals`.
- `summaryCount` (integer, optional): Fetch brief summaries for top N results (0 = PMIDs only). Above the 50 cap, pass the remaining PMIDs to pubmed_fetch_articles. Default: `0`.

## Example call

Request headers and body:

```http
POST /mcp HTTP/1.1
Host: gateway.mcpharbor.dev
Authorization: Bearer <your gateway API key>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: pubmed__pubmed_search_articles
```

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/clientCapabilities": {},
      "io.modelcontextprotocol/clientInfo": {
        "name": "example-agent",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/protocolVersion": "2026-07-28"
    },
    "arguments": {
      "query": "example"
    },
    "name": "pubmed__pubmed_search_articles"
  }
}
```

A successful response:

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "_meta": {
      "dev.mcpharbor.gateway/call": {
        "chargedMicroUsd": 100,
        "id": "<the id of this charge>"
      }
    },
    "content": [
      {
        "text": "<whatever the upstream tool returned>",
        "type": "text"
      }
    ],
    "resultType": "complete"
  }
}
```

This call costs $0.0001 (100 micro-USD). Reading this page and listing the tool cost nothing.
The `dev.mcpharbor.gateway/call` record in the result is the receipt for that charge. Each
POST is metered separately, so sending the same call again buys another one: see
[agent.txt](https://gateway.mcpharbor.dev/agent.txt), section 7, before retrying.

## Attribution

This provider requires the attribution below wherever you use results from its tools.
Reproduce it verbatim:

> NCBI's Disclaimer and Copyright notice must be evident to users of your product

## Tool definition

Exactly as `tools/list` returns it (free):

```json
{
  "_meta": {
    "dev.mcpharbor.gateway/pricing": {
      "currency": "USD",
      "pricePerCallMicroUsd": 100
    }
  },
  "annotations": {
    "openWorldHint": true,
    "readOnlyHint": true
  },
  "description": "Search PubMed with full query syntax, filters, and date ranges. Returns PMIDs and optional brief summaries. Supports field-specific filters (author, journal, MeSH terms), common filters (language, species, free full text), and pagination via offset for paging through large result sets.",
  "inputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "author": {
        "description": "Filter by author name (e.g. \"Smith J\")",
        "type": "string"
      },
      "dateRange": {
        "description": "Filter by date range. The filter is applied only when both `minDate` and `maxDate` are non-empty; either one empty disables the entire date range.",
        "properties": {
          "dateType": {
            "default": "pdat",
            "description": "Date type: pdat (publication), mdat (modification), edat (entrez)",
            "enum": [
              "pdat",
              "mdat",
              "edat"
            ],
            "type": "string"
          },
          "maxDate": {
            "description": "End date (YYYY/MM/DD, YYYY/MM, or YYYY); empty string disables this bound",
            "pattern": "^$|^\\d{4}([/\\-.]\\d{1,2}([/\\-.]\\d{1,2})?)?$",
            "type": "string"
          },
          "minDate": {
            "description": "Start date (YYYY/MM/DD, YYYY/MM, or YYYY); empty string disables this bound",
            "pattern": "^$|^\\d{4}([/\\-.]\\d{1,2}([/\\-.]\\d{1,2})?)?$",
            "type": "string"
          }
        },
        "required": [
          "minDate",
          "maxDate"
        ],
        "type": "object"
      },
      "freeFullText": {
        "description": "Only include free full text articles",
        "type": "boolean"
      },
      "hasAbstract": {
        "description": "Only include articles with abstracts",
        "type": "boolean"
      },
      "journal": {
        "description": "Filter by journal name",
        "type": "string"
      },
      "language": {
        "description": "Filter by language (e.g. \"english\")",
        "type": "string"
      },
      "maxResults": {
        "default": 20,
        "description": "Maximum results to return",
        "maximum": 1000,
        "minimum": 1,
        "type": "integer"
      },
      "meshTerms": {
        "description": "Filter by MeSH terms. Multiple terms are AND'd — all must match.",
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "offset": {
        "default": 0,
        "description": "Result offset for pagination (0-based). PubMed serves at most the first 9999 records of a result set, so this caps at 9998; narrow the query or add filters to reach anything beyond it.",
        "maximum": 9998,
        "minimum": 0,
        "type": "integer"
      },
      "publicationTypes": {
        "description": "Filter by publication type (e.g. \"Review\", \"Clinical Trial\", \"Meta-Analysis\"). Multiple values are OR'd — any match qualifies.",
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "query": {
        "description": "PubMed search query (supports full NCBI syntax). Must carry a search term: a value that is blank once markup is stripped is rejected rather than sent to PubMed as an empty term.",
        "minLength": 1,
        "type": "string"
      },
      "sort": {
        "default": "relevance",
        "description": "Sort order: relevance (default), pub_date (newest first), author, or journal",
        "enum": [
          "relevance",
          "pub_date",
          "author",
          "journal"
        ],
        "type": "string"
      },
      "species": {
        "description": "Filter by species",
        "enum": [
          "humans",
          "animals"
        ],
        "type": "string"
      },
      "summaryCount": {
        "default": 0,
        "description": "Fetch brief summaries for top N results (0 = PMIDs only). Above the 50 cap, pass the remaining PMIDs to pubmed_fetch_articles.",
        "maximum": 50,
        "minimum": 0,
        "type": "integer"
      }
    },
    "required": [
      "query"
    ],
    "type": "object"
  },
  "name": "pubmed__pubmed_search_articles",
  "outputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "anyOf": [
      {
        "not": {
          "required": [
            "error"
          ]
        },
        "required": [
          "query",
          "offset",
          "pmids",
          "summaries",
          "searchUrl",
          "effectiveQuery",
          "totalCount",
          "appliedFilters"
        ]
      },
      {
        "required": [
          "error"
        ]
      }
    ],
    "properties": {
      "appliedFilters": {
        "additionalProperties": false,
        "description": "Normalized filter values that were applied to the PubMed query",
        "properties": {
          "author": {
            "description": "Author filter applied to the search",
            "type": "string"
          },
          "dateRange": {
            "additionalProperties": false,
            "description": "Date range filter applied to the search",
            "properties": {
              "dateType": {
                "description": "Applied date field used for the range filter",
                "enum": [
                  "pdat",
                  "mdat",
                  "edat"
                ],
                "type": "string"
              },
              "maxDate": {
                "description": "Applied maximum date",
                "type": "string"
              },
              "minDate": {
                "description": "Applied minimum date",
                "type": "string"
              }
            },
            "required": [
              "minDate",
              "maxDate",
              "dateType"
            ],
            "type": "object"
          },
          "freeFullText": {
            "description": "Whether results were restricted to free full-text articles",
            "type": "boolean"
          },
          "hasAbstract": {
            "description": "Whether results were restricted to articles with abstracts",
            "type": "boolean"
          },
          "journal": {
            "description": "Journal filter applied to the search",
            "type": "string"
          },
          "language": {
            "description": "Language filter applied to the search",
            "type": "string"
          },
          "meshTerms": {
            "description": "MeSH term filters applied to the search",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "publicationTypes": {
            "description": "Publication type filters applied to the search",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "species": {
            "description": "Species filter applied to the search",
            "enum": [
              "humans",
              "animals"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "effectiveQuery": {
        "description": "Sanitized query sent to PubMed after applying all active filters",
        "type": "string"
      },
      "error": {
        "additionalProperties": {},
        "description": "Present when the call failed. Absent on success.",
        "properties": {
          "code": {
            "description": "JSON-RPC error code for this failure.",
            "maximum": 9007199254740991,
            "minimum": -9007199254740991,
            "type": "integer"
          },
          "data": {
            "additionalProperties": {},
            "properties": {
              "reason": {
                "description": "Machine-readable failure mode. Declared by this tool: `queue_full`: Local NCBI request queue is at capacity. `ncbi_unreachable`: NCBI E-utilities is unreachable after all retry attempts. `ncbi_deadline_exceeded`: Total request deadline expired before NCBI returned a response. `ncbi_invalid_response`: NCBI returned a body that could not be parsed (invalid XML/JSON). `ncbi_resource_not_found`: NCBI returned a structured \"not found\" error for the requested ID(s). `blank_query`: The query holds no search term once whitespace, and any markup the tool strips first, are removed — so NCBI would receive a blank term. Other values are possible when a failure originates below the handler.",
                "examples": [
                  "queue_full",
                  "ncbi_unreachable",
                  "ncbi_deadline_exceeded",
                  "ncbi_invalid_response",
                  "ncbi_resource_not_found",
                  "blank_query"
                ],
                "type": "string"
              },
              "recovery": {
                "additionalProperties": {},
                "description": "Actionable next step for the caller.",
                "properties": {
                  "hint": {
                    "type": "string"
                  }
                },
                "required": [
                  "hint"
                ],
                "type": "object"
              },
              "retryable": {
                "description": "Whether retrying may succeed.",
                "type": "boolean"
              }
            },
            "type": "object"
          },
          "message": {
            "description": "Human-readable description of what went wrong.",
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "type": "object"
      },
      "notice": {
        "description": "Optional guidance when the result set does not reflect what was asked for — a field tag PubMed ignored, a phrase it matched nothing for, a dateRange dropped for having one bound, no matches at all, or paging past the end. Absent when nothing applies.",
        "type": "string"
      },
      "offset": {
        "description": "Result offset used",
        "type": "number"
      },
      "pmids": {
        "description": "PubMed IDs",
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "query": {
        "description": "Original query",
        "type": "string"
      },
      "searchUrl": {
        "description": "PubMed search URL",
        "type": "string"
      },
      "summaries": {
        "description": "Brief summaries (empty array when summaryCount is 0)",
        "items": {
          "additionalProperties": false,
          "description": "Brief article summary",
          "properties": {
            "authors": {
              "description": "Formatted author string — the first three of the record's own authors, then \"et al.\". On an NCBI Bookshelf chapter these are the chapter's authors; the book's editors are reported separately in `editors`.",
              "type": "string"
            },
            "bookTitle": {
              "description": "Title of the book an NCBI Bookshelf record belongs to, e.g. \"GeneReviews(®)\". Present instead of `source` on a book record; absent on a journal article.",
              "type": "string"
            },
            "docType": {
              "description": "What PubMed classifies this record as: \"chapter\" or \"book\" for an NCBI Bookshelf record, \"citation\" for an ordinary journal article. Absent when PubMed supplies none.",
              "type": "string"
            },
            "doi": {
              "description": "DOI, cased as NCBI reports it. DOIs are case-insensitive by spec and no case normalization is applied here, so casing can differ from a Europe PMC-sourced `doi` — compare the two case-insensitively.",
              "type": "string"
            },
            "editors": {
              "description": "Editors of the containing book, kept out of `authors` so they cannot displace the record's own authors. Absent on a journal article and on a book that credits no editors.",
              "items": {
                "description": "One editor, \"Surname Initials\" as ESummary renders it",
                "type": "string"
              },
              "type": "array"
            },
            "pmcId": {
              "description": "PMC ID",
              "type": "string"
            },
            "pmcUrl": {
              "description": "PMC URL",
              "type": "string"
            },
            "pmid": {
              "description": "PubMed ID",
              "type": "string"
            },
            "pubDate": {
              "description": "Publication date",
              "type": "string"
            },
            "publisherName": {
              "description": "Publisher of the book an NCBI Bookshelf record belongs to. Present only on a book record; absent on a journal article.",
              "type": "string"
            },
            "pubmedUrl": {
              "description": "PubMed URL",
              "type": "string"
            },
            "source": {
              "description": "Journal the article appeared in. Absent on an NCBI Bookshelf record, which has no journal — its venue is in `bookTitle` and `publisherName` instead, and `docType` says which kind of record it is.",
              "type": "string"
            },
            "title": {
              "description": "Article title",
              "type": "string"
            }
          },
          "required": [
            "pmid"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "totalCount": {
        "description": "Total matching articles",
        "type": "number"
      }
    },
    "type": "object"
  },
  "title": "Pubmed Search Articles"
}
```