Skip to main content
Glama

crossref-mcp-server

Get Reference List

crossref_get_references
Read-onlyIdempotent

Returns the outgoing reference list for a DOI — the works cited by this paper. Each reference includes the deposited citation string and, where Crossref has resolved it, a DOI you can look up with crossref_get_work. Results are paged: referenceCount is the full deposited total, and when more remain the response carries a nextOffset to pass back as offset. Reference list coverage varies by publisher; many older works and non-participating publishers have no indexed references. Incoming citations — the works that cite this paper — are not available through Crossref; use OpenAlex for that.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "doi": "<doi>"
    },
    "name": "crossref_get_references"
  }
}

Input Schema

NameRequiredDescriptionDefault
doiYesDOI in the format "10.NNNN/suffix", e.g. "10.1038/nature12373". A resolver-wrapped form — "https://doi.org/10.1038/nature12373", "https://dx.doi.org/…", "doi:10.1038/nature12373" — is accepted and unwrapped.
limitNoMaximum number of references to return in one page (1–4000 per call, default 100). A larger value, up to 100000, returns 4000 and says so in notice; nextOffset continues after the references returned. Most works fit in a single page; bibliography records can carry tens of thousands.
offsetNoZero-based index of the first reference to return. Pass the nextOffset value from the previous response to continue through a long reference list.

Output Schema

NameRequiredDescriptionDefault
capNoThe limit that was applied to this page.
doiNoDOI of the citing work
errorNoPresent when the call failed. Absent on success.
shownNoNumber of references returned in this page.
noticeNoCoverage guidance when no references are indexed, a range explanation when the requested offset is past the end of the list, or which references this page covers and the offset that reaches the next ones. Leads with the value requested and the cap applied when limit was above its per-call cap. Absent on a page that holds the whole list with limit within its cap.
offsetNoZero-based index of the first returned reference within the deposited list
truncatedNoTrue when references remain beyond this page. Absent when the page is the last.
nextOffsetNoOffset to pass in the next call to retrieve the following page. Absent when this page reaches the end of the reference list.
referencesNoPage of the outgoing reference list
referenceCountNoTotal number of references in the deposited list

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `rate_limited`: Crossref answered HTTP 429 and the limit did not clear inside the retry budget. `upstream_unavailable`: Crossref was unreachable, returned a 5xx status, or served an HTML error page instead of JSON. `malformed_response`: Crossref returned HTTP 200 with a body that is not valid JSON, or with facet counts in a shape this server does not read. `request_timeout`: Crossref did not respond within CROSSREF_TIMEOUT_MS, or answered HTTP 408/504. `doi_not_found`: Valid DOI format but no Crossref record exists. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `rate_limited`: Crossref answered HTTP 429 and the limit did not clear inside the retry budget, or answered it to the single-attempt published-version lookup on a preprint. `upstream_unavailable`: Crossref was unreachable, returned a 5xx status, or served an HTML error page instead of JSON. `malformed_response`: Crossref returned HTTP 200 with a body that is not valid JSON, or with facet counts in a shape this server does not read. `request_timeout`: Crossref did not respond within CROSSREF_TIMEOUT_MS, did not answer before the 25 s request deadline (CROSSREF_TIMEOUT_MS when longer) that bounds every retry, or answered HTTP 408/504. `doi_not_found`: Valid DOI format but no Crossref record exists. Other values are possible when a failure originates below the handler."
  2. Changed2 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of references to return in one page (1–2500 per call, default 100). A larger value, up to 100000, returns 2500 and says so in notice; nextOffset continues after the references returned. Most works fit in a single page; bibliography records can carry tens of thousands."New value: +"Maximum number of references to return in one page (1–4000 per call, default 100). A larger value, up to 100000, returns 4000 and says so in notice; nextOffset continues after the references returned. Most works fit in a single page; bibliography records can carry tens of thousands."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `rate_limited`: Crossref answered HTTP 429 and the limit did not clear inside the retry budget. `upstream_unavailable`: Crossref was unreachable, returned a 5xx status, or served an HTML error page instead of JSON. `malformed_response`: Crossref returned HTTP 200 with a body that is not valid JSON. `request_timeout`: Crossref did not respond within CROSSREF_TIMEOUT_MS, or answered HTTP 408/504. `doi_not_found`: Valid DOI format but no Crossref record exists. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `rate_limited`: Crossref answered HTTP 429 and the limit did not clear inside the retry budget. `upstream_unavailable`: Crossref was unreachable, returned a 5xx status, or served an HTML error page instead of JSON. `malformed_response`: Crossref returned HTTP 200 with a body that is not valid JSON, or with facet counts in a shape this server does not read. `request_timeout`: Crossref did not respond within CROSSREF_TIMEOUT_MS, or answered HTTP 408/504. `doi_not_found`: Valid DOI format but no Crossref record exists. Other values are possible when a failure originates below the handler."
  3. Changed1 schema field changed
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of references to return in one page (1–500 per call, default 100). A larger value, up to 100000, returns 500 and says so in notice; nextOffset continues after the references returned. Most works fit in a single page; bibliography records can carry tens of thousands."New value: +"Maximum number of references to return in one page (1–2500 per call, default 100). A larger value, up to 100000, returns 2500 and says so in notice; nextOffset continues after the references returned. Most works fit in a single page; bibliography records can carry tens of thousands."
  4. Changed8 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of references to return in one page (1–500, default 100). Most works fit in a single page; bibliography records can carry tens of thousands."New value: +"Maximum number of references to return in one page (1–500 per call, default 100). A larger value, up to 100000, returns 500 and says so in notice; nextOffset continues after the references returned. Most works fit in a single page; bibliography records can carry tens of thousands."
    • changedInput schema / properties / limit / maximum
      Previous value: -500New value: +100000
    • changedOutput schema / properties / notice / description
      Previous value: -"Coverage guidance when no references are indexed, or a range explanation when the requested offset is past the end of the list. Absent on a normal page."New value: +"Coverage guidance when no references are indexed, a range explanation when the requested offset is past the end of the list, or which references this page covers and the offset that reaches the next ones. Leads with the value requested and the cap applied when limit was above its per-call cap. Absent on a page that holds the whole list with limit within its cap."
    • addedOutput schema / properties / references / items / properties / doiAssertedBy
      Added value: +{
      +  "description": "Who supplied the DOI: \"publisher\" when the citing work's publisher deposited it, \"crossref\" when Crossref matched the citation to it.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / references / items / properties / edition
      Added value: +{
      +  "description": "Edition of the cited book, as deposited",
      +  "type": "string"
      +}
    • addedOutput schema / properties / references / items / properties / issue
      Added value: +{
      +  "description": "Issue",
      +  "type": "string"
      +}
    • addedOutput schema / properties / references / items / properties / seriesTitle
      Added value: +{
      +  "description": "Title of the series the cited work belongs to, with inline formatting markup removed",
      +  "type": "string"
      +}
    • addedOutput schema / properties / references / items / properties / volumeTitle
      Added value: +{
      +  "description": "Title of the cited book or proceedings volume, with inline formatting markup removed. The only title on many book and chapter citations.",
      +  "type": "string"
      +}
  5. First observed

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly/idempotent annotations, the description discloses pagination mechanics (referenceCount is the full deposited total; nextOffset is passed back as offset), partial DOI resolution ('where Crossref has resolved it'), and variable coverage by publisher. These are exactly the traits an agent needs to interpret empty or short results, and none of them are recoverable from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Opens with the definition, then moves through return content, pagination, coverage caveats, and the alternative for incoming citations — a logical order with no filler. Every sentence contributes a distinct operational fact.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description is not obliged to enumerate return fields, and it wisely focuses on the non-obvious parts: pagination loop, resolution gaps, and publisher-dependent coverage. Nothing an agent needs in order to call this correctly or interpret an empty result is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the field-level documentation is already in place and the baseline is 3. The description still adds value by framing offset as the value carried in nextOffset and by clarifying that referenceCount is the deposited total rather than the page size, which explains the limit/offset relationship rather than restating it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Returns the outgoing reference list for a DOI') and immediately disambiguates direction with 'the works cited by this paper'. That contrast against incoming citations makes it unmistakably distinct from a cited-by or search tool without requiring the sibling schema to be opened.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear routing guidance: resolved reference DOIs can be looked up with crossref_get_work, and incoming citations must go to OpenAlex instead. It also warns that non-participating publishers and many older works have no indexed references, which is a practical when-it-fails caveat. It stops short of an explicit 'prefer X when you want Y' statement against each sibling, but the context needed to choose is present.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.