Tutorial: PubMed - Gnist Context

Science

Data source: PubMed (NCBI)

Overview

PubMed wraps PubMed (NCBI), handling authentication, pagination, and rate limits for you. This tutorial covers all 6 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-pubmed": {
      "url": "https://context.gnist.ai/mcp/pubmed/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (6)

`search_pubmed`

Search PubMed for biomedical literature. Searches 35M+ abstracts across all biomedical and life science fields. Returns title, authors, journal, publication date, and DOI. Args: query: Search query. Supports PubMed syntax (e.g., "diabetes[MeSH] AND insulin", "COVID-19 vaccine efficacy"). Plain keywords also work. max_results: Number of results to return (1–100, default 10). date_from: Filter by publication date start (YYYY/MM/DD or YYYY). date_to: Filter by publication date end (YYYY/MM/DD or YYYY). Returns: List of articles with pmid, title, authors, journal, pub_date, and doi. Note: Abstracts are not included in search results — use get_article for full text.

Parameter	Type	Required	Description
`query`	string	required	Search query. Supports PubMed syntax (e.g., "diabetes[MeSH] AND insulin", "COVID-19 vaccine efficacy"). Plain keywords also work.
`max_results`	integer	optional	Number of results to return (1–100, default 10). (default: `10`)
`date_from`	any	optional	Filter by publication date start (YYYY/MM/DD or YYYY).
`date_to`	any	optional	Filter by publication date end (YYYY/MM/DD or YYYY).

curl -X POST "https://context.gnist.ai/mcp/pubmed/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_pubmed", "arguments": {"query": "renewable energy"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/pubmed/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'renewable energy'},
            'name': 'search_pubmed'}},
)
print(resp.json())

`get_article`

Fetch full metadata and abstract for a PubMed article. Args: pmid: PubMed ID (e.g., "33972843"). Found in search_pubmed results. Returns: Full article record including title, authors, abstract, journal, pub_date, and doi.

Parameter	Type	Required	Description
`pmid`	string	required	PubMed ID (e.g., "33972843"). Found in search_pubmed results.

curl -X POST "https://context.gnist.ai/mcp/pubmed/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_article", "arguments": {"pmid": "12345"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/pubmed/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'pmid': '12345'}, 'name': 'get_article'}},
)
print(resp.json())

`mesh_lookup`

Look up a MeSH (Medical Subject Headings) term. MeSH is the NLM's controlled vocabulary for indexing biomedical literature. Use this to find canonical term names, definitions, and related terms. Args: term: The medical term to look up (e.g., "Diabetes Mellitus", "Hypertension"). Returns: MeSH entry with canonical name, scope note (definition), tree numbers, and synonyms. Returns empty result if term not found.

Parameter	Type	Required	Description
`term`	string	required	The medical term to look up (e.g., "Diabetes Mellitus", "Hypertension").

curl -X POST "https://context.gnist.ai/mcp/pubmed/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "mesh_lookup", "arguments": {"term": "renewable energy"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/pubmed/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'term': 'renewable energy'}, 'name': 'mesh_lookup'}},
)
print(resp.json())

`search_trials`

Search ClinicalTrials.gov for clinical trials by condition. Returns trial summaries including NCT ID, title, status, phase, conditions, interventions, and sponsor. Args: condition: Medical condition to search for. status: Trial status filter. phase: Trial phase filter. country: Country filter. max_results: Number of results (1–50, default 10). Returns: List of trial summaries.

Parameter	Type	Required	Description
`condition`	string	required	Medical condition to search for (e.g., "COVID-19", "Type 2 Diabetes").
`status`	any	optional	Trial status filter (e.g., RECRUITING, COMPLETED, ACTIVE_NOT_RECRUITING).
`phase`	any	optional	Trial phase filter (e.g., PHASE1, PHASE2, PHASE3, PHASE4).
`country`	any	optional	Country filter (e.g., United States, Norway).
`max_results`	integer	optional	Number of results to return (1–50, default 10). (default: `10`)

curl -X POST "https://context.gnist.ai/mcp/pubmed/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_trials", "arguments": {"condition": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/pubmed/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'condition': 'example'}, 'name': 'search_trials'}},
)
print(resp.json())

`get_trial`

Fetch detailed information about a specific clinical trial. Args: nct_id: ClinicalTrials.gov NCT ID. Returns: Full trial record including eligibility criteria and locations.

Parameter	Type	Required	Description
`nct_id`	string	required	ClinicalTrials.gov NCT ID (e.g., "NCT04470427").

curl -X POST "https://context.gnist.ai/mcp/pubmed/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_trial", "arguments": {"nct_id": "12345"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/pubmed/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'nct_id': '12345'}, 'name': 'get_trial'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/pubmed/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/pubmed/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_pubmed to find items, then get_article to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

Date range filtering
Use date range parameters to narrow results to a specific time window. Dates are typically in YYYY-MM-DD format.

FAQ

What data does PubMed provide?

Biomedical literature search — PubMed abstracts, citations, and MeSH term lookup. For clinical trials use the clinicaltrials server. It exposes 6 tools: search_pubmed, get_article, mesh_lookup, search_trials, get_trial, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the PubMed API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.