pubchem-mcp-server

Get Compound Interactions

pubchem_get_compound_interactions

Read-onlyIdempotent

Fetch drug-food interactions and assay-named molecular targets for a PubChem compound, paged by kind with source and outcome counts.

Instructions

Get a compound's interaction data: drug-food interactions, and the molecular targets its bioassays name — one entry per target as kinds defines it, with its assay counts by outcome and most potent active value, Active targets first, most potent first. Each entry carries its originating source. Results are paged per kind, with the record total and the next offset reported for each. Drug-food coverage is richest for approved drugs; target covers any compound PubChem has assay data for, and pubchem_get_bioactivity lists one target's assays when given the entry's GeneID or accession. Drug-drug interactions (DrugBank) are unavailable while PubChem's SDQ service refuses automated requests: an explicit drug-drug request is reported in failedKinds while the other kinds still return.

Input Schema

Name	Required	Description
`cid`	Yes	PubChem Compound ID. Resolve from name/SMILES with pubchem_search_compounds.
`kinds`	No	Interaction kinds to fetch. "drug-food" (dietary interactions, from PUG View), "target" (molecular targets from the compound's assay summary: one entry per Gene ID with the accessions the table pairs with it, and one per identifier it never pairs, so a Gene ID and an accession that no row pairs are separate entries even when they name the same protein), "drug-drug" (interactions with other drugs, from PubChem's SDQ service, which refuses automated requests, so it is reported in failedKinds). Default: ["drug-food"].
`offset`	No	Zero-based start position within each requested kind, counted in records (molecular targets, for target) rather than returned entries. The same offset applies to every kind in the call, and the kinds advance at different rates — when paging past the first page, request one kind per call and pass that kind's nextOffset. Default: 0.
`maxEntries`	No	Max entries per kind per page. The per-call cap is 50: a larger value (up to 1000) reads a page of 50 per kind and is reported in cappedInputs. Well-studied drugs have a long tail of interactions; use offset to reach the ones past this page. Default: 10.

Output Schema

Name	Required	Description
`cid`	No	PubChem Compound ID.
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance when a kind failed, when no interaction data was found, when the offset runs past every requested kind, when target names could not be retrieved, or when further pages remain. Absent when this page is complete and every kind resolved.
`offset`	No	Zero-based start position read within each requested kind.
`paging`	No	Per-kind page position, one entry per requested kind that was retrieved. A kind listed in failedKinds is absent — its position is unknown, not exhausted.
`entries`	No	Interaction entries across the requested kinds.
`truncated`	No	True when at least one requested kind has source records remaining past this page. Which kinds, and how many records each holds, is in paging[].truncated / paging[].totalRecords.
`nextOffset`	No	Offset to pass on the next call, reported when exactly one requested kind has records remaining. Omitted when none do, and when several do — those advance to different positions, so read paging[].nextOffset instead.
`failedKinds`	No	Interaction kinds that could not be retrieved (comma-separated). The returned entries cover the kinds that succeeded. The notice says, per failed kind, whether a retry can help: a timeout, rate limit, network error, unreadable response, or upstream 5xx other than 501 can clear, while an HTTP 400, 403, or 501, a response in a shape the server does not expect, or a refusal from PubChem's SDQ service (drug-drug) does not.
`cappedInputs`	No	Inputs that asked for more than their per-call cap, with the value requested and the value served. An ID batch lists the IDs past the cap in unprocessed. Omitted when every input was within its cap.
`returnedCount`	No	Total interaction entries returned across all kinds.
`requestedKinds`	No	Interaction kinds requested (comma-separated).

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.8.0Oct 29, 2026

changedOutput schema / properties / failedKinds / description

Previous value: -"Interaction kinds that could not be retrieved (comma-separated). The returned entries cover the kinds that succeeded. The notice says, per failed kind, whether a retry can help: a timeout or upstream error can clear, while a refusal from PubChem's SDQ service (drug-drug) does not."New value: +"Interaction kinds that could not be retrieved (comma-separated). The returned entries cover the kinds that succeeded. The notice says, per failed kind, whether a retry can help: a timeout, rate limit, network error, unreadable response, or upstream 5xx other than 501 can clear, while an HTTP 400, 403, or 501, a response in a shape the server does not expect, or a refusal from PubChem's SDQ service (drug-drug) does not."

Changed9 schema fields changedv0.7.1Oct 24, 2026

changedInput schema / properties / kinds / default

Previous value: -[
-  "drug-drug"
-]New value: +[
+  "drug-food"
+]

changedInput schema / properties / kinds / description

Previous value: -"Interaction kinds to fetch. \"drug-drug\" (interactions with other drugs), \"drug-food\" (dietary interactions), \"target\" (binding/activity against molecular targets). \"drug-drug\" and \"target\" come from PubChem's SDQ service, which can refuse automated requests; \"drug-food\" comes from PUG View. Per-target activity is also available from pubchem_get_bioactivity. Default: [\"drug-drug\"]."New value: +"Interaction kinds to fetch. \"drug-food\" (dietary interactions, from PUG View), \"target\" (molecular targets from the compound's assay summary: one entry per Gene ID with the accessions the table pairs with it, and one per identifier it never pairs, so a Gene ID and an accession that no row pairs are separate entries even when they name the same protein), \"drug-drug\" (interactions with other drugs, from PubChem's SDQ service, which refuses automated requests, so it is reported in failedKinds). Default: [\"drug-food\"]."

changedInput schema / properties / offset / description

Previous value: -"Zero-based start position within each requested kind, counted in source records rather than returned entries. The same offset applies to every kind in the call, and the kinds advance at different rates — when paging past the first page, request one kind per call and pass that kind's nextOffset. Default: 0."New value: +"Zero-based start position within each requested kind, counted in records (molecular targets, for target) rather than returned entries. The same offset applies to every kind in the call, and the kinds advance at different rates — when paging past the first page, request one kind per call and pass that kind's nextOffset. Default: 0."

changedOutput schema / properties / entries / items / properties / partner / description

Previous value: -"Interacting compound, food, or target name as the source reports it."New value: +"Interacting compound as the source reports it. For a target: its gene or protein name and organism, then the identifier pubchem_get_bioactivity filters on (GeneID:N → targetGeneId, accession:X → targetAccession); the identifier alone when no name resolves. A target whose identifiers join several Gene IDs is named by the accession they share and says \"group of N Gene IDs\"."

changedOutput schema / properties / entries / items / properties / source / description

Previous value: -"Originating source (e.g. \"DrugBank\", \"BindingDB\")."New value: +"Originating source (e.g. \"DrugBank\", \"PubChem BioAssay\")."

changedOutput schema / properties / entries / items / properties / text / description

Previous value: -"The interaction statement."New value: +"The interaction statement. For a target: the assays naming it by outcome and its most potent Active value with that AID, in µM."

changedOutput schema / properties / failedKinds / description

Previous value: -"Interaction kinds that could not be retrieved (comma-separated). The returned entries cover the kinds that succeeded. The notice says, per failed kind, whether a retry can help: a timeout or upstream error can clear, while a refusal from PubChem's SDQ service (drug-drug, target) does not."New value: +"Interaction kinds that could not be retrieved (comma-separated). The returned entries cover the kinds that succeeded. The notice says, per failed kind, whether a retry can help: a timeout or upstream error can clear, while a refusal from PubChem's SDQ service (drug-drug) does not."

changedOutput schema / properties / notice / description

Previous value: -"Guidance when a kind failed, when no interaction data was found, when the offset runs past every requested kind, or when further pages remain. Absent when this page is complete and every kind resolved."New value: +"Guidance when a kind failed, when no interaction data was found, when the offset runs past every requested kind, when target names could not be retrieved, or when further pages remain. Absent when this page is complete and every kind resolved."

changedOutput schema / properties / paging / items / properties / totalRecords / description

Previous value: -"Source records available for this kind, across all pages. Entries are derived from these records and can be fewer: a \"target\" record naming no molecular target and a \"drug-drug\" record carrying no statement both yield nothing, and duplicate measurements collapse within a page. Pages divide the records, not the entries, so a duplicate split across two pages is reported on both."New value: +"Records available for this kind, across all pages: interaction records for drug-drug and drug-food, molecular targets for target. Entries are derived from these records and can be fewer: a drug-drug record carrying no statement yields nothing. Pages divide the records, not the entries."

Changed6 schema fields changedv0.7.0Oct 16, 2026

changedInput schema / properties / cid / maximum

Previous value: -9007199254740991New value: +2147483647

changedInput schema / properties / kinds / description

Previous value: -"Interaction kinds to fetch. \"drug-drug\" (interactions with other drugs), \"drug-food\" (dietary interactions), \"target\" (binding/activity against molecular targets). Default: [\"drug-drug\"]."New value: +"Interaction kinds to fetch. \"drug-drug\" (interactions with other drugs), \"drug-food\" (dietary interactions), \"target\" (binding/activity against molecular targets). \"drug-drug\" and \"target\" come from PubChem's SDQ service, which can refuse automated requests; \"drug-food\" comes from PUG View. Per-target activity is also available from pubchem_get_bioactivity. Default: [\"drug-drug\"]."

changedInput schema / properties / maxEntries / description

Previous value: -"Max entries per kind per page (1-50). Well-studied drugs have a long tail of interactions; use offset to reach the ones past this page. Default: 10."New value: +"Max entries per kind per page. The per-call cap is 50: a larger value (up to 1000) reads a page of 50 per kind and is reported in cappedInputs. Well-studied drugs have a long tail of interactions; use offset to reach the ones past this page. Default: 10."

changedInput schema / properties / maxEntries / maximum
```
Previous value: -50New value: +1000
```

addedOutput schema / properties / cappedInputs

Added value: +{
+  "description": "Inputs that asked for more than their per-call cap, with the value requested and the value served. An ID batch lists the IDs past the cap in unprocessed. Omitted when every input was within its cap.",
+  "items": {
+    "additionalProperties": false,
+    "description": "One input served at its per-call cap.",
+    "properties": {
+      "input": {
+        "description": "Input name, e.g. \"maxResults\" or \"cids\".",
+        "type": "string"
+      },
+      "requested": {
+        "description": "Value requested: the page size, or the number of IDs in the batch.",
+        "type": "number"
+      },
+      "served": {
+        "description": "Value served: the per-call cap.",
+        "type": "number"
+      },
+      "unprocessed": {
+        "description": "ID batches only: IDs past the cap, listed in unprocessed in input order.",
+        "type": "number"
+      }
+    },
+    "required": [
+      "input",
+      "requested",
+      "served"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / properties / failedKinds / description

Previous value: -"Interaction kinds that could not be retrieved (comma-separated). The returned entries cover the kinds that succeeded; retry to re-attempt the failed ones."New value: +"Interaction kinds that could not be retrieved (comma-separated). The returned entries cover the kinds that succeeded. The notice says, per failed kind, whether a retry can help: a timeout or upstream error can clear, while a refusal from PubChem's SDQ service (drug-drug, target) does not."

Changed2 schema fields changedv0.6.5Sep 25, 2026
- removedInput schema / properties / cid / exclusiveMinimum
```
Removed value: -0
```
- addedInput schema / properties / cid / minimum
```
Added value: +1
```

Changed7 schema fields changedv0.6.1Aug 28, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "cid",
+      "entries",
+      "paging",
+      "requestedKinds",
+      "returnedCount",
+      "truncated",
+      "offset"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "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.",
+          "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"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when at least one requested kind has source records remaining past this page. Which kinds, and how many records each holds, is in paging[].truncated / paging[].totalRecords.",
+  "type": "boolean"
+}

removedOutput schema / required

Removed value: -[
-  "cid",
-  "entries",
-  "paging",
-  "requestedKinds",
-  "returnedCount",
-  "offset"
-]

Changed8 schema fields changedv0.6.0Jul 30, 2026

changedInput schema / properties / maxEntries / description

Previous value: -"Max entries per kind (1-50). Well-studied drugs have a long tail of interactions. Default: 10."New value: +"Max entries per kind per page (1-50). Well-studied drugs have a long tail of interactions; use offset to reach the ones past this page. Default: 10."

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "Zero-based start position within each requested kind, counted in source records rather than returned entries. The same offset applies to every kind in the call, and the kinds advance at different rates — when paging past the first page, request one kind per call and pass that kind's nextOffset. Default: 0.",
+  "maximum": 2147483646,
+  "minimum": 0,
+  "type": "integer"
+}

removedOutput schema / properties / entries / items / properties / severity

Removed value: -{
-  "description": "Raw severity as the source reports it — not normalized across sources, and frequently unset (most sources embed severity in the statement text).",
-  "type": "string"
-}

addedOutput schema / properties / nextOffset

Added value: +{
+  "description": "Offset to pass on the next call, reported when exactly one requested kind has records remaining. Omitted when none do, and when several do — those advance to different positions, so read paging[].nextOffset instead.",
+  "type": "number"
+}

changedOutput schema / properties / notice / description

Previous value: -"Guidance when no interaction data was found for the requested kinds."New value: +"Guidance when a kind failed, when no interaction data was found, when the offset runs past every requested kind, or when further pages remain. Absent when this page is complete and every kind resolved."

addedOutput schema / properties / offset

Added value: +{
+  "description": "Zero-based start position read within each requested kind.",
+  "type": "number"
+}

addedOutput schema / properties / paging

Added value: +{
+  "description": "Per-kind page position, one entry per requested kind that was retrieved. A kind listed in failedKinds is absent — its position is unknown, not exhausted.",
+  "items": {
+    "additionalProperties": false,
+    "description": "Page position for one interaction kind.",
+    "properties": {
+      "kind": {
+        "description": "Interaction category this page covers.",
+        "enum": [
+          "drug-drug",
+          "drug-food",
+          "target"
+        ],
+        "type": "string"
+      },
+      "nextOffset": {
+        "description": "Offset to pass on the next call to continue this kind past the current page. Omitted when no records remain.",
+        "type": "number"
+      },
+      "returnedCount": {
+        "description": "Interaction entries returned for this kind.",
+        "type": "number"
+      },
+      "totalRecords": {
+        "description": "Source records available for this kind, across all pages. Entries are derived from these records and can be fewer: a \"target\" record naming no molecular target and a \"drug-drug\" record carrying no statement both yield nothing, and duplicate measurements collapse within a page. Pages divide the records, not the entries, so a duplicate split across two pages is reported on both.",
+        "type": "number"
+      },
+      "truncated": {
+        "description": "True when source records remain for this kind past the current page.",
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "kind",
+      "returnedCount",
+      "totalRecords",
+      "truncated"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / required

Previous value: -[
-  "cid",
-  "entries",
-  "requestedKinds",
-  "returnedCount"
-]New value: +[
+  "cid",
+  "entries",
+  "paging",
+  "requestedKinds",
+  "returnedCount",
+  "offset"
+]

Addedv0.2.2Jun 4, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations cover the safety profile (readOnly, idempotent, openWorld), and the description adds substantial behavior beyond them: per-kind paging with record totals and next offsets, ordering guarantees, per-entry source attribution, and the failedKinds path when SDQ refuses drug-drug requests. It stops short of describing response shape (left to the output schema) or rate limiting, so not a full 5.

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

Conciseness4/5

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

Front-loaded with purpose and ordering, then paging behavior, then the sibling route, then the drug-drug caveat — a sensible information hierarchy. It is a single dense paragraph with long em-dash clauses, so it is efficient but slightly harder to scan than a structured list would be.

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?

For a paged, multi-kind read tool with an output schema, the description covers everything an agent needs to call it correctly: which kinds exist, their differing coverage, ordering, paging semantics, and the degradation path for the unavailable kind. Return value structure is correctly delegated to the output schema.

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 baseline is 3; the description still adds real semantic value beyond it — that offset is counted in records rather than returned entries, that one offset applies to every kind, and that kinds advance at different rates so paging past page one should request a single kind. The 'long tail' note on maxEntries also motivates the offset. Remaining overlap with the schema caps it at 4.

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?

Opens with a specific verb+resource ('Get a compound's interaction data') and immediately enumerates the kinds returned, the ordering ('Active targets first, most potent first'), and per-entry contents. It differentiates itself from pubchem_get_bioactivity by name and scope, so an agent can pick between them without opening either schema.

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

Usage Guidelines5/5

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

Explicitly routes the agent: use pubchem_get_bioactivity when you already have a GeneID/accession for one target's assays, and this tool otherwise. It also states coverage expectations ('drug-food coverage is richest for approved drugs') and the paging strategy (one kind per call past the first page), plus what happens on an explicit drug-drug request.

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

Deploy Server

Get Compound Interactions

Instructions

Input Schema

Output Schema

Schema Changelog

TDQS

Other Tools