# `crossref__crossref_search_journals`
**Search Journals**
Finds Crossref journal records by ISSN or title query. Provide issn for an exact single-journal lookup, or query for title-based search returning up to rows results. Title-query results page with offset — the nextOffset enrichment carries the value for the following page, up to offset + rows = 100000. Set include_works to true to also return a page of the matched journal's most recent works by publication date; that list pages two ways. works_offset is the simple one and is capped ten times lower at works_offset + rows = 10000. works_cursor has no ceiling and reaches the whole works list: pass works_cursor="*" on the first call, then chain the nextWorksCursor token from each response. The two cannot be combined, and a cursor walk always starts at the newest work — it cannot resume from an offset. Returns journal metadata: title, publisher, ISSN-L, subject areas, and total DOI count.
- Server: [Crossref](https://gateway.mcpharbor.dev/docs/servers/crossref) (`dev.mcpharbor.gateway/crossref`)
- 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/crossref`
- Upstream tool: exposed by the provider; called through this gateway as `crossref__crossref_search_journals`
- Provider terms: (verified 2026-09-19)
- Upstream API documentation:
- Rate limit: 50 requests per minute
## Parameters
- `include_works` (boolean, optional): When true, also return a page of the journal's most recent works by publication date. Requires an unambiguous journal — pass issn when a title query matches more than one. A journal with no ISSN re... Default: `false`.
- `issn` (string, optional): ISSN for exact single-journal lookup (print or electronic, with or without hyphen). Example: "1234-5678".
- `offset` (integer, optional): Zero-based offset into the title-query journal list. Pass the nextOffset value from the previous response to continue. Ignored when issn is set, which resolves exactly one record. Default: `0`.
- `query` (string, optional): Journal title search query, e.g. "Nature" or "Journal of Machine Learning Research"
- `rows` (number, optional): Maximum number of journals to return for title queries, or works when include_works is true (1–100, default 10) Default: `10`.
- `works_cursor` (string, optional): Cursor token for deep paging of the journal works list when include_works is true. Pass "*" to start the walk at the newest work, then pass the nextWorksCursor value from each response. Has no offs...
- `works_offset` (integer, optional): Zero-based offset into the journal works list when include_works is true. Pass the nextWorksOffset value from the previous response to continue. Capped at works_offset + rows = 10000; use works_cur... Default: `0`.
## 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: crossref__crossref_search_journals
```
```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": {
"include_works": true
},
"name": "crossref__crossref_search_journals"
}
}
```
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 asks for no attribution. Their terms still apply: see the table above.
## 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": "Finds Crossref journal records by ISSN or title query. Provide issn for an exact single-journal lookup, or query for title-based search returning up to rows results. Title-query results page with offset — the nextOffset enrichment carries the value for the following page, up to offset + rows = 100000. Set include_works to true to also return a page of the matched journal's most recent works by publication date; that list pages two ways. works_offset is the simple one and is capped ten times lower at works_offset + rows = 10000. works_cursor has no ceiling and reaches the whole works list: pass works_cursor=\"*\" on the first call, then chain the nextWorksCursor token from each response. The two cannot be combined, and a cursor walk always starts at the newest work — it cannot resume from an offset. Returns journal metadata: title, publisher, ISSN-L, subject areas, and total DOI count.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"include_works": {
"default": false,
"description": "When true, also return a page of the journal's most recent works by publication date. Requires an unambiguous journal — pass issn when a title query matches more than one. A journal with no ISSN registered has no addressable works list; the works lookup is then skipped and the notice enrichment says so.",
"type": "boolean"
},
"issn": {
"description": "ISSN for exact single-journal lookup (print or electronic, with or without hyphen). Example: \"1234-5678\".",
"pattern": "^\\d{4}-?\\d{3}[\\dX]$",
"type": "string"
},
"offset": {
"default": 0,
"description": "Zero-based offset into the title-query journal list. Pass the nextOffset value from the previous response to continue. Ignored when issn is set, which resolves exactly one record.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"query": {
"description": "Journal title search query, e.g. \"Nature\" or \"Journal of Machine Learning Research\"",
"type": "string"
},
"rows": {
"default": 10,
"description": "Maximum number of journals to return for title queries, or works when include_works is true (1–100, default 10)",
"maximum": 100,
"minimum": 1,
"type": "number"
},
"works_cursor": {
"description": "Cursor token for deep paging of the journal works list when include_works is true. Pass \"*\" to start the walk at the newest work, then pass the nextWorksCursor value from each response. Has no offset ceiling and cannot be combined with works_offset. Each token runs about 1500 characters and is returned on both result surfaces, a fixed cost per page — raise rows to spread it across more works on a long walk.",
"type": "string"
},
"works_offset": {
"default": 0,
"description": "Zero-based offset into the journal works list when include_works is true. Pass the nextWorksOffset value from the previous response to continue. Capped at works_offset + rows = 10000; use works_cursor to read the whole list. Cannot be combined with works_cursor.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"name": "crossref__crossref_search_journals",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"journals",
"journalCount",
"journalsTotal"
]
},
{
"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: `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. `issn_not_found`: ISSN lookup returned 404 — ISSN is not registered in Crossref. `ambiguous_journal`: include_works is true but the title query matched more than one journal, making the target ambiguous. `offset_too_large`: offset + rows exceeds the 100000-record ceiling Crossref allows on journal title search. `works_offset_too_large`: works_offset + rows exceeds the 10000-record ceiling Crossref allows on a journal works list. `works_cursor_offset_conflict`: include_works is true and works_cursor was supplied alongside a works_offset above zero. Other values are possible when a failure originates below the handler.",
"examples": [
"rate_limited",
"upstream_unavailable",
"malformed_response",
"request_timeout",
"issn_not_found",
"ambiguous_journal",
"offset_too_large",
"works_offset_too_large",
"works_cursor_offset_conflict"
],
"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"
},
"journalCount": {
"description": "Number of journal records returned in this page",
"type": "number"
},
"journals": {
"description": "Matching journal records",
"items": {
"additionalProperties": false,
"description": "Journal record",
"properties": {
"issn": {
"description": "All ISSN variants for this journal",
"items": {
"type": "string"
},
"type": "array"
},
"issnL": {
"description": "Linking ISSN (ISSN-L). Absent when the journal has no linking ISSN registered — Crossref reports that as an explicit null rather than an omitted key.",
"type": "string"
},
"publisher": {
"description": "Publisher name",
"type": "string"
},
"subjects": {
"description": "Subject classifications",
"items": {
"additionalProperties": false,
"description": "Subject",
"properties": {
"name": {
"description": "Subject area name",
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"type": "array"
},
"title": {
"description": "Journal title",
"type": "string"
},
"totalDois": {
"description": "Total registered DOIs in this journal",
"type": "number"
}
},
"type": "object"
},
"type": "array"
},
"journalsTotal": {
"description": "Total journal records matching the query in Crossref",
"type": "number"
},
"nextOffset": {
"description": "Value to pass as offset on the next call for the following page of journals. Absent when this page ends the matches or the next page would breach the 100000-record offset ceiling.",
"type": "number"
},
"nextWorksCursor": {
"description": "Value to pass as works_cursor on the next call for the following page of works. Present only on a page requested with works_cursor, and absent once the walk reaches the end of the works list.",
"type": "string"
},
"nextWorksOffset": {
"description": "Value to pass as works_offset on the next call for the following page of works. Absent when this page ends the works list, the next page would breach the 10000-record offset ceiling, or the page was requested with works_cursor.",
"type": "number"
},
"notice": {
"description": "Guidance on a page that needs a caveat: a query nothing matched, an offset past the end of a list that did match, a page that stops at one of the route offset ceilings with records still unretrieved, or an include_works request that was skipped because the matched journal has no registered ISSN to address its works list by. Absent otherwise.",
"type": "string"
},
"recentWorks": {
"description": "Page of works from the matched journal, ordered by publication date (newest first). Requires include_works, and absent even then when the matched journal has no registered ISSN — the works list is addressable by ISSN alone, and the notice enrichment says so.",
"items": {
"additionalProperties": false,
"description": "Work summary",
"properties": {
"doi": {
"description": "Work DOI",
"type": "string"
},
"isReferencedByCount": {
"description": "Incoming citation count",
"type": "number"
},
"published": {
"additionalProperties": false,
"description": "Publication date — the first of published, published-print, and published-online that names one. A component Crossref records as unknown is omitted, and so is every component below it.",
"properties": {
"month": {
"description": "Month",
"type": "number"
},
"year": {
"description": "Year",
"type": "number"
}
},
"type": "object"
},
"title": {
"description": "Work title",
"type": "string"
},
"type": {
"description": "Work type",
"type": "string"
}
},
"required": [
"doi"
],
"type": "object"
},
"type": "array"
},
"worksTotal": {
"description": "Total works count for the journal, when include_works is true",
"type": "number"
}
},
"type": "object"
},
"title": "Search Journals"
}
```