# `pubmed__pubmed_lookup_citation`

**Pubmed Lookup Citation**

Look up PubMed IDs from partial bibliographic citations. Useful when you have a reference (journal, year, volume, page, author) and need the PMID — deterministic citation matching, more reliable than free-text search for structured references. Each citation must include at least journal or year (ECitMatch primary-keys on journal+volume+page; author-only or volume-only inputs guarantee no match); more fields = better match accuracy.

- 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_lookup_citation`
- 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

- `citations` (array, required): Citations to look up. More fields = better match accuracy.

## 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_lookup_citation
```

```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": {
      "citations": []
    },
    "name": "pubmed__pubmed_lookup_citation"
  }
}
```

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": "Look up PubMed IDs from partial bibliographic citations. Useful when you have a reference (journal, year, volume, page, author) and need the PMID — deterministic citation matching, more reliable than free-text search for structured references. Each citation must include at least journal or year (ECitMatch primary-keys on journal+volume+page; author-only or volume-only inputs guarantee no match); more fields = better match accuracy.",
  "inputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "citations": {
        "description": "Citations to look up. More fields = better match accuracy.",
        "items": {
          "description": "Citation to match against PubMed. Must include at least journal or year — ECitMatch primary-keys on journal+volume+page, so author-only or volume-only inputs guarantee no match.",
          "properties": {
            "authorName": {
              "description": "Author name, typically \"lastname initials\" (e.g., \"mann bj\"). Cannot contain a pipe (\"|\") or a line break.",
              "pattern": "^[^|\\r\\n]*$",
              "type": "string"
            },
            "firstPage": {
              "description": "First page number. Cannot contain a pipe (\"|\") or a line break.",
              "pattern": "^[^|\\r\\n]*$",
              "type": "string"
            },
            "journal": {
              "description": "Journal title or ISO abbreviation (e.g., \"proc natl acad sci u s a\"). Cannot contain a pipe (\"|\") or a line break.",
              "pattern": "^[^|\\r\\n]*$",
              "type": "string"
            },
            "key": {
              "description": "Arbitrary label to track this citation in results. Auto-assigned if omitted. Echoed back unchanged and never sent to NCBI, so any character is accepted here.",
              "type": "string"
            },
            "volume": {
              "description": "Volume number. Cannot contain a pipe (\"|\") or a line break.",
              "pattern": "^[^|\\r\\n]*$",
              "type": "string"
            },
            "year": {
              "description": "Publication year (e.g., \"1991\"). Cannot contain a pipe (\"|\") or a line break.",
              "pattern": "^[^|\\r\\n]*$",
              "type": "string"
            }
          },
          "type": "object"
        },
        "maxItems": 25,
        "minItems": 1,
        "type": "array"
      }
    },
    "required": [
      "citations"
    ],
    "type": "object"
  },
  "name": "pubmed__pubmed_lookup_citation",
  "outputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "anyOf": [
      {
        "not": {
          "required": [
            "error"
          ]
        },
        "required": [
          "results",
          "totalMatched",
          "totalSubmitted",
          "totalWarnings"
        ]
      },
      {
        "required": [
          "error"
        ]
      }
    ],
    "properties": {
      "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). 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"
                ],
                "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"
      },
      "results": {
        "description": "Match results, one per input citation",
        "items": {
          "additionalProperties": false,
          "description": "Per-citation match result",
          "properties": {
            "candidatePmids": {
              "description": "Candidate PMIDs returned when the citation matched ambiguously. Add more bibliographic fields and retry to disambiguate, or fetch each candidate via pubmed_fetch_articles to pick the intended one.",
              "items": {
                "description": "PMID",
                "type": "string"
              },
              "type": "array"
            },
            "detail": {
              "description": "Additional detail returned by ECitMatch for non-exact matches",
              "type": "string"
            },
            "key": {
              "description": "Citation tracking key",
              "type": "string"
            },
            "matched": {
              "description": "Whether a PMID was found",
              "type": "boolean"
            },
            "matchedFirstAuthor": {
              "description": "First author of the matched article (e.g., \"Husain M\"). Useful eyeball signal for verifying a match.",
              "type": "string"
            },
            "pmid": {
              "description": "Matched PubMed ID",
              "type": "string"
            },
            "status": {
              "description": "Lookup outcome classification for this citation",
              "enum": [
                "matched",
                "not_found",
                "ambiguous"
              ],
              "type": "string"
            },
            "warnings": {
              "description": "Non-fatal warnings about this match. A PMID may be returned even when the queried author or year disagrees with the matched article — verify before treating the PMID as authoritative.",
              "items": {
                "additionalProperties": false,
                "description": "Non-fatal warning about the match",
                "properties": {
                  "code": {
                    "description": "Machine-readable warning code",
                    "enum": [
                      "author_mismatch",
                      "year_mismatch"
                    ],
                    "type": "string"
                  },
                  "message": {
                    "description": "Human-readable description of the warning",
                    "type": "string"
                  }
                },
                "required": [
                  "code",
                  "message"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "key",
            "matched",
            "status"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "totalMatched": {
        "description": "Number of citations with PMID matches",
        "type": "number"
      },
      "totalSubmitted": {
        "description": "Number of citations submitted",
        "type": "number"
      },
      "totalWarnings": {
        "description": "Number of matched citations that carry at least one warning",
        "type": "number"
      }
    },
    "type": "object"
  },
  "title": "Pubmed Lookup Citation"
}
```