# `pubmed__pubmed_lookup_mesh`
**Pubmed Lookup Mesh**
Search and explore the MeSH (Medical Subject Headings) controlled vocabulary. Returns descriptor records with tree numbers, scope notes, and entry terms, plus pagination via offset for paging past the maxResults cap.
- 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_mesh`
- 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
- `includeDetails` (boolean, optional): Fetch full MeSH records (scope notes, tree numbers, entry terms) Default: `true`.
- `maxResults` (integer, optional): Maximum results Default: `10`.
- `offset` (integer, optional): Result offset for pagination (0-based). Pass the \`nextOffset\` from the previous response to get the following page; the exact-descriptor match is pinned to the first page only. Default: `0`.
- `query` (string, required): MeSH descriptor name or free-text term to look up. Must carry a term: a blank or whitespace-only value is rejected rather than searched.
## 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_lookup_mesh
```
```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_lookup_mesh"
}
}
```
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": "Search and explore the MeSH (Medical Subject Headings) controlled vocabulary. Returns descriptor records with tree numbers, scope notes, and entry terms, plus pagination via offset for paging past the maxResults cap.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"includeDetails": {
"default": true,
"description": "Fetch full MeSH records (scope notes, tree numbers, entry terms)",
"type": "boolean"
},
"maxResults": {
"default": 10,
"description": "Maximum results",
"maximum": 50,
"minimum": 1,
"type": "integer"
},
"offset": {
"default": 0,
"description": "Result offset for pagination (0-based). Pass the `nextOffset` from the previous response to get the following page; the exact-descriptor match is pinned to the first page only.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"query": {
"description": "MeSH descriptor name or free-text term to look up. Must carry a term: a blank or whitespace-only value is rejected rather than searched.",
"minLength": 1,
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "pubmed__pubmed_lookup_mesh",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"query",
"offset",
"results",
"totalCount"
]
},
{
"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). `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"
},
"nextOffset": {
"description": "Offset to request for the next page. Omitted when this is the last page, so its absence is the end-of-results signal.",
"type": "number"
},
"notice": {
"description": "Optional guidance when no descriptors matched or the offset overshot the result set — suggests spell-check, free-text search, or resetting the offset. Absent on successful result pages.",
"type": "string"
},
"offset": {
"description": "Result offset this page was read from",
"type": "number"
},
"query": {
"description": "Original search query",
"type": "string"
},
"results": {
"description": "Matching MeSH records",
"items": {
"additionalProperties": false,
"description": "Matching MeSH descriptor record",
"properties": {
"entrezUid": {
"description": "NCBI Entrez UID for this record — the join key for E-utilities (eSummary/eFetch db=mesh).",
"type": "string"
},
"entryTerms": {
"description": "Synonyms / entry terms",
"items": {
"type": "string"
},
"type": "array"
},
"meshId": {
"description": "Canonical MeSH DescriptorUI (e.g. \"D003924\") — resolves at the MeSH Browser and NLM linked data. Falls back to the raw Entrez UID when a record is not decodable.",
"type": "string"
},
"name": {
"description": "Descriptor name",
"type": "string"
},
"scopeNote": {
"description": "Scope note",
"type": "string"
},
"treeNumbers": {
"description": "Navigable MeSH tree numbers (e.g. \"D02.078.370.141.450\"). Omitted for supplementary concept records (SCRs), which map to a heading rather than occupying a tree position.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"meshId",
"entrezUid",
"name"
],
"type": "object"
},
"type": "array"
},
"totalCount": {
"description": "Total MeSH descriptors matching the query upstream, before the maxResults cap",
"type": "number"
}
},
"type": "object"
},
"title": "Pubmed Lookup Mesh"
}
```