# `pubchem__pubchem_search_compounds`

**Search Compounds**

Search PubChem for chemical compounds by identifier (name, SMILES, or InChIKey, batched up to 25), molecular formula in Hill notation, substructure or superstructure containment, or 2D Tanimoto similarity. Returns a page of CIDs — reach matches past maxResults with offset. Optionally hydrate results with properties to avoid a follow-up pubchem_get_compound_details call.

- Server: [PubChem](https://gateway.mcpharbor.dev/docs/servers/pubchem) (`dev.mcpharbor.gateway/pubchem`)
- 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/pubchem`
- Upstream tool: exposed by the provider; called through this gateway as `pubchem__pubchem_search_compounds`
- Provider terms: <https://www.ncbi.nlm.nih.gov/home/about/policies/> (verified 2026-09-19)
- Upstream API documentation: <https://pubchem.ncbi.nlm.nih.gov/docs/pug-rest>
- Rate limit: 350 requests per minute
- Attribution required: Attribution to source recommended, not mandatory

## Parameters

- `allowOtherElements` (boolean, optional): Formula search only. When true, includes compounds with additional elements beyond the formula. Default: `false`.
- `formula` (string, optional): Required for formula search. Molecular formula in Hill notation (e.g. "C6H12O6", "CaH2O2").
- `identifierType` (string, optional): Required for identifier search. Type of chemical identifier: "name", "smiles", or "inchikey". One of: `name`, `smiles`, `inchikey`.
- `identifiers` (array, optional): Required for identifier search. Array of identifiers to resolve (1-25). Examples: \["aspirin", "ibuprofen"\] for name, \["CC(=O)OC1=CC=CC=C1C(=O)O"\] for SMILES, \["BSYNRYMUTXBXSQ-UHFFFAOYSA-N"\] for inc...
- `maxResults` (integer, optional): Maximum CIDs to return per page (1-200). Use offset to reach matches past this page. Default: 20. Default: `20`.
- `offset` (integer, optional): Zero-based index of the first CID to return. Pass the nextOffset from a previous call to read the following page. Identifier lookups resolve every match up front, so paging them is free; formula, s... Default: `0`.
- `properties` (array, optional): Optional: fetch these properties for each result, avoiding a follow-up details call. E.g. \["MolecularFormula", "MolecularWeight", "CanonicalSMILES"\].
- `query` (string, optional): Required for substructure/superstructure/similarity searches. A SMILES string (e.g. "CC(=O)O") or PubChem CID as a string (e.g. "2244").
- `queryType` (string, optional): Required for structure/similarity searches. Format of the query: "smiles" or "cid". One of: `smiles`, `cid`.
- `searchType` (string, required): Search strategy. "identifier": name/SMILES/InChIKey lookup. "formula": molecular formula. "substructure": find compounds containing the query as a substructure. "superstructure": find compounds tha... One of: `identifier`, `formula`, `substructure`, `superstructure`, `similarity`.
- `threshold` (number, optional): Similarity search only. Minimum Tanimoto similarity (70-100). 90+ for close analogs, 70-80 for scaffold hops. Default: 90. Default: `90`.

## 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: pubchem__pubchem_search_compounds
```

```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": {
      "searchType": "identifier"
    },
    "name": "pubchem__pubchem_search_compounds"
  }
}
```

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:

> Attribution to source recommended, not mandatory

## Tool definition

Exactly as `tools/list` returns it (free):

```json
{
  "_meta": {
    "dev.mcpharbor.gateway/pricing": {
      "currency": "USD",
      "pricePerCallMicroUsd": 100
    }
  },
  "annotations": {
    "idempotentHint": true,
    "openWorldHint": true,
    "readOnlyHint": true
  },
  "description": "Search PubChem for chemical compounds by identifier (name, SMILES, or InChIKey, batched up to 25), molecular formula in Hill notation, substructure or superstructure containment, or 2D Tanimoto similarity. Returns a page of CIDs — reach matches past maxResults with offset. Optionally hydrate results with properties to avoid a follow-up pubchem_get_compound_details call.",
  "inputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "allowOtherElements": {
        "default": false,
        "description": "Formula search only. When true, includes compounds with additional elements beyond the formula.",
        "type": "boolean"
      },
      "formula": {
        "description": "Required for formula search. Molecular formula in Hill notation (e.g. \"C6H12O6\", \"CaH2O2\").",
        "type": "string"
      },
      "identifierType": {
        "description": "Required for identifier search. Type of chemical identifier: \"name\", \"smiles\", or \"inchikey\".",
        "enum": [
          "name",
          "smiles",
          "inchikey"
        ],
        "type": "string"
      },
      "identifiers": {
        "description": "Required for identifier search. Array of identifiers to resolve (1-25). Examples: [\"aspirin\", \"ibuprofen\"] for name, [\"CC(=O)OC1=CC=CC=C1C(=O)O\"] for SMILES, [\"BSYNRYMUTXBXSQ-UHFFFAOYSA-N\"] for inchikey (27-char block format).",
        "items": {
          "type": "string"
        },
        "maxItems": 25,
        "minItems": 1,
        "type": "array"
      },
      "maxResults": {
        "default": 20,
        "description": "Maximum CIDs to return per page (1-200). Use offset to reach matches past this page. Default: 20.",
        "maximum": 200,
        "minimum": 1,
        "type": "integer"
      },
      "offset": {
        "default": 0,
        "description": "Zero-based index of the first CID to return. Pass the nextOffset from a previous call to read the following page. Identifier lookups resolve every match up front, so paging them is free; formula, substructure, superstructure, and similarity searches have to ask PubChem for offset + maxResults records to reach a page, so deep pages cost progressively more upstream — hence the 10000 ceiling. Default: 0.",
        "maximum": 10000,
        "minimum": 0,
        "type": "integer"
      },
      "properties": {
        "description": "Optional: fetch these properties for each result, avoiding a follow-up details call. E.g. [\"MolecularFormula\", \"MolecularWeight\", \"CanonicalSMILES\"].",
        "items": {
          "enum": [
            "MolecularFormula",
            "MolecularWeight",
            "CanonicalSMILES",
            "IsomericSMILES",
            "InChI",
            "InChIKey",
            "IUPACName",
            "Title",
            "XLogP",
            "ExactMass",
            "MonoisotopicMass",
            "TPSA",
            "Complexity",
            "Charge",
            "HBondDonorCount",
            "HBondAcceptorCount",
            "RotatableBondCount",
            "HeavyAtomCount",
            "IsotopeAtomCount",
            "AtomStereoCount",
            "DefinedAtomStereoCount",
            "UndefinedAtomStereoCount",
            "BondStereoCount",
            "DefinedBondStereoCount",
            "UndefinedBondStereoCount",
            "CovalentUnitCount",
            "Volume3D"
          ],
          "type": "string"
        },
        "type": "array"
      },
      "query": {
        "description": "Required for substructure/superstructure/similarity searches. A SMILES string (e.g. \"CC(=O)O\") or PubChem CID as a string (e.g. \"2244\").",
        "type": "string"
      },
      "queryType": {
        "description": "Required for structure/similarity searches. Format of the query: \"smiles\" or \"cid\".",
        "enum": [
          "smiles",
          "cid"
        ],
        "type": "string"
      },
      "searchType": {
        "description": "Search strategy. \"identifier\": name/SMILES/InChIKey lookup. \"formula\": molecular formula. \"substructure\": find compounds containing the query as a substructure. \"superstructure\": find compounds that are themselves substructures of the query. \"similarity\": 2D Tanimoto similarity to the query.",
        "enum": [
          "identifier",
          "formula",
          "substructure",
          "superstructure",
          "similarity"
        ],
        "type": "string"
      },
      "threshold": {
        "default": 90,
        "description": "Similarity search only. Minimum Tanimoto similarity (70-100). 90+ for close analogs, 70-80 for scaffold hops. Default: 90.",
        "maximum": 100,
        "minimum": 70,
        "type": "number"
      }
    },
    "required": [
      "searchType"
    ],
    "type": "object"
  },
  "name": "pubchem__pubchem_search_compounds",
  "outputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "anyOf": [
      {
        "not": {
          "required": [
            "error"
          ]
        },
        "required": [
          "results",
          "searchType",
          "offset"
        ]
      },
      {
        "required": [
          "error"
        ]
      }
    ],
    "properties": {
      "cap": {
        "description": "The maxResults cap that was applied.",
        "type": "number"
      },
      "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: `missing_identifier_args`: searchType is \"identifier\" but identifierType or identifiers were omitted. `missing_formula`: searchType is \"formula\" but the formula field was omitted. `missing_structure_args`: substructure/superstructure/similarity search missing query or queryType. `invalid_cid_query`: structure/similarity search with queryType \"cid\" but query is not a positive integer CID. Other values are possible when a failure originates below the handler.",
                "examples": [
                  "missing_identifier_args",
                  "missing_formula",
                  "missing_structure_args",
                  "invalid_cid_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 pass on the next call to continue past this page. Omitted when no further matches remain.",
        "type": "number"
      },
      "notice": {
        "description": "Recovery guidance when no compounds matched, when the offset runs past the matches observed, when identifiers failed to resolve, or when further pages remain. Absent when this page is complete and every identifier resolved.",
        "type": "string"
      },
      "offset": {
        "description": "Zero-based index of the first CID returned.",
        "type": "number"
      },
      "results": {
        "description": "Matching compounds.",
        "items": {
          "additionalProperties": false,
          "description": "Matching compound entry.",
          "properties": {
            "cid": {
              "description": "PubChem Compound ID.",
              "type": "number"
            },
            "identifier": {
              "description": "Echoed input identifier (identifier mode only).",
              "type": "string"
            },
            "properties": {
              "additionalProperties": {},
              "description": "Compound properties keyed by name (echoes input.properties; only present when requested).",
              "propertyNames": {
                "type": "string"
              },
              "type": "object"
            }
          },
          "required": [
            "cid"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "searchType": {
        "description": "Search strategy used: identifier, formula, substructure, superstructure, or similarity.",
        "type": "string"
      },
      "shown": {
        "description": "CIDs returned on this page.",
        "type": "number"
      },
      "totalFound": {
        "description": "Exact number of matching CIDs across all pages. Omitted when a formula, substructure, superstructure, or similarity search saturated the records it requested — PubChem returns no match count for those, so totalFoundAtLeast reports a floor instead.",
        "type": "number"
      },
      "totalFoundAtLeast": {
        "description": "Lower bound on matching CIDs, reported in place of totalFound when the exact count is unavailable. At least this many match, and the true total may be higher; page further with offset to observe more.",
        "type": "number"
      },
      "truncated": {
        "description": "True when matching CIDs remain past this page.",
        "type": "boolean"
      },
      "unresolvedIdentifiers": {
        "description": "Identifier-mode only: input identifiers that resolved to no CID. Omitted when every identifier resolved and for non-identifier searches.",
        "items": {
          "type": "string"
        },
        "type": "array"
      }
    },
    "type": "object"
  },
  "title": "Search Compounds"
}
```