# `pubmed__pubmed_find_related`
**Pubmed Find Related**
Find articles related to a source article — similar content (similar), articles citing this one (cited_by), or articles this one cites (references). Uses NCBI ELink as the primary source; falls back to Europe PMC then OpenAlex when NCBI is unavailable.
- 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_find_related`
- Provider terms: (verified 2026-09-19)
- Upstream API documentation:
- Rate limit: 150 requests per minute
- Attribution required: NCBI's Disclaimer and Copyright notice must be evident to users of your product
## Parameters
- `maxResults` (integer, optional): Maximum related articles Default: `10`.
- `offset` (integer, optional): Result offset for pagination (0-based); page through results by incrementing by maxResults Default: `0`.
- `pmid` (string, required): Source PubMed ID
- `relationship` (string, optional): Relationship type: similar (content-based), cited_by (articles citing this one), references (articles this one cites) One of: `similar`, `cited_by`, `references`. Default: `similar`.
## Example call
Request headers and body:
```http
POST /mcp HTTP/1.1
Host: gateway.mcpharbor.dev
Authorization: Bearer
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: pubmed__pubmed_find_related
```
```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": {
"pmid": "example"
},
"name": "pubmed__pubmed_find_related"
}
}
```
A successful response:
```json
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"_meta": {
"dev.mcpharbor.gateway/call": {
"chargedMicroUsd": 100,
"id": ""
}
},
"content": [
{
"text": "",
"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": "Find articles related to a source article — similar content (similar), articles citing this one (cited_by), or articles this one cites (references). Uses NCBI ELink as the primary source; falls back to Europe PMC then OpenAlex when NCBI is unavailable.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"maxResults": {
"default": 10,
"description": "Maximum related articles",
"maximum": 50,
"minimum": 1,
"type": "integer"
},
"offset": {
"default": 0,
"description": "Result offset for pagination (0-based); page through results by incrementing by maxResults",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"pmid": {
"description": "Source PubMed ID",
"pattern": "^\\d+$",
"type": "string"
},
"relationship": {
"default": "similar",
"description": "Relationship type: similar (content-based), cited_by (articles citing this one), references (articles this one cites)",
"enum": [
"similar",
"cited_by",
"references"
],
"type": "string"
}
},
"required": [
"pmid"
],
"type": "object"
},
"name": "pubmed__pubmed_find_related",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"sourcePmid",
"relationship",
"offset",
"articles",
"totalCount",
"source"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"articles": {
"description": "Related articles",
"items": {
"additionalProperties": false,
"description": "Related article with enriched summary",
"properties": {
"authors": {
"description": "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 in `editors`.",
"type": "string"
},
"bookTitle": {
"description": "Title of the book an NCBI Bookshelf record belongs to. 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"
},
"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"
},
"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"
},
"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"
},
"coverageFailures": {
"description": "Reference-coverage fallbacks that failed instead of answering, so the reference set is unverified rather than confirmed absent. Absent when every provider consulted answered.",
"items": {
"additionalProperties": false,
"description": "One coverage provider that could not be checked",
"properties": {
"provider": {
"description": "Reference-coverage provider that failed",
"enum": [
"europepmc",
"openalex"
],
"type": "string"
},
"reason": {
"description": "Declared failure reason, e.g. europepmc_unreachable or provider_disabled",
"type": "string"
},
"retryable": {
"description": "Whether a retry can reach this provider",
"type": "boolean"
}
},
"required": [
"provider",
"reason",
"retryable"
],
"type": "object"
},
"type": "array"
},
"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). `europepmc_unreachable`: Europe PMC was unreachable after all retry attempts. `europepmc_invalid_response`: Europe PMC returned a body that could not be parsed (invalid JSON or XML). `europepmc_invalid_input`: Europe PMC rejected the request input (empty query, unknown sort field, malformed parameter). `openalex_unreachable`: OpenAlex was unreachable after all retry attempts. `openalex_invalid_response`: OpenAlex returned a body that could not be parsed (invalid JSON). `all_providers_failed`: Every provider eligible for the requested relationship failed; none answered. 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",
"europepmc_unreachable",
"europepmc_invalid_response",
"europepmc_invalid_input",
"openalex_unreachable",
"openalex_invalid_response",
"all_providers_failed"
],
"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": "Guidance when results are empty, a fallback provider answered, offset overshot, a fallback provider could not be reached, or upstream rows were excluded for carrying no PubMed PMID. Absent on a clean NCBI result page.",
"type": "string"
},
"offset": {
"description": "Result offset used",
"type": "number"
},
"relationship": {
"description": "Relationship type used",
"enum": [
"similar",
"cited_by",
"references"
],
"type": "string"
},
"source": {
"description": "Provider that answered this request",
"enum": [
"ncbi",
"europepmc",
"openalex"
],
"type": "string"
},
"sourcePmid": {
"description": "Source PubMed ID",
"type": "string"
},
"totalCount": {
"description": "Total related articles found before windowing. A Europe PMC or OpenAlex total may shrink to the PubMed-addressable count once a request window covers the whole upstream set, since rows without a PubMed PMID cannot be returned.",
"type": "number"
}
},
"type": "object"
},
"title": "Pubmed Find Related"
}
```