# `pubmed__pubmed_convert_ids`
**Pubmed Convert Ids**
Convert between article identifiers (DOI, PMID, PMCID). Accepts up to 50 IDs of a single type per request. Only resolves articles indexed in PubMed Central — for articles not in PMC, use pubmed_search_articles instead.
- 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_convert_ids`
- 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
- `idType` (string, required): The type of IDs being submitted. Required so the API can unambiguously resolve them. One of: `pmcid`, `pmid`, `doi`.
- `ids` (array, required): Article identifiers to convert — one identifier per element, all of the same type. Each element is checked against \`idType\` before the request: \`doi\` starts with "10." and carries a "/" ("10.1093/n...
## 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_convert_ids
```
```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": {
"idType": "pmcid",
"ids": []
},
"name": "pubmed__pubmed_convert_ids"
}
}
```
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": "Convert between article identifiers (DOI, PMID, PMCID). Accepts up to 50 IDs of a single type per request. Only resolves articles indexed in PubMed Central — for articles not in PMC, use pubmed_search_articles instead.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"idType": {
"description": "The type of IDs being submitted. Required so the API can unambiguously resolve them.",
"enum": [
"pmcid",
"pmid",
"doi"
],
"type": "string"
},
"ids": {
"description": "Article identifiers to convert — one identifier per element, all of the same type. Each element is checked against `idType` before the request: `doi` starts with \"10.\" and carries a \"/\" (\"10.1093/nar/gks1195\"); `pmid` is digits (\"23193287\"); `pmcid` is digits with an optional \"PMC\" prefix (\"PMC3531190\" or \"3531190\"). No element may contain a comma or whitespace — a packed value like \"23193287,37952131\" is rejected, so split it across elements.",
"items": {
"minLength": 1,
"type": "string"
},
"maxItems": 50,
"minItems": 1,
"type": "array"
}
},
"required": [
"ids",
"idType"
],
"type": "object"
},
"name": "pubmed__pubmed_convert_ids",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"records",
"totalConverted",
"totalSubmitted"
]
},
{
"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). `malformed_id`: An `ids` element does not match the declared `idType` — most often several identifiers packed into one element, which the comma-delimited upstream batch would split into extra records. 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",
"malformed_id"
],
"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"
},
"records": {
"description": "Conversion results, one per input ID",
"items": {
"additionalProperties": false,
"description": "Per-ID conversion record",
"properties": {
"doi": {
"description": "Digital Object Identifier, cased as the PMC ID Converter reports it; absent if no DOI is on record. DOIs are case-insensitive by spec and no case normalization is applied here, so casing can differ from a Europe PMC-sourced `doi` — compare the two case-insensitively.",
"type": "string"
},
"errmsg": {
"description": "Error message if conversion failed. Presence of `errmsg` is the failure signal; absence means the conversion succeeded.",
"type": "string"
},
"pmcid": {
"description": "PubMed Central ID; absent if the article has no PMC copy",
"type": "string"
},
"pmid": {
"description": "PubMed ID; absent if no mapping was found",
"type": "string"
},
"requestedId": {
"description": "The ID that was submitted",
"type": "string"
}
},
"required": [
"requestedId"
],
"type": "object"
},
"type": "array"
},
"totalConverted": {
"description": "Number of IDs successfully converted",
"type": "number"
},
"totalSubmitted": {
"description": "Number of IDs submitted",
"type": "number"
}
},
"type": "object"
},
"title": "Pubmed Convert Ids"
}
```