Tutorial: OpenFDA - Gnist Context

Science

Data source: openFDA

Overview

OpenFDA wraps openFDA, handling authentication, pagination, and rate limits for you. This tutorial covers all 5 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-openfda": {
      "url": "https://context.gnist.ai/mcp/openfda/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`search_adverse_events`

Search FDA adverse event reports (FAERS) for a drug or active ingredient. Args: drug_name: Drug name — brand (e.g. "Tylenol") or generic (e.g. "acetaminophen"). reaction: Optional MedDRA reaction term to filter by (e.g. "headache", "nausea"). date_from: Start date filter in YYYYMMDD format (e.g. "20200101"). date_to: End date filter in YYYYMMDD format (e.g. "20221231"). limit: Number of reports to return (1–100, default 10). Returns: Dictionary with count and adverse event reports (drug name, reactions, seriousness, outcome codes). Data sourced from FDA FAERS, updated quarterly.

Parameter	Type	Required	Description
`drug_name`	string	required	Drug name — brand (e.g. "Tylenol") or generic (e.g. "acetaminophen").
`reaction`	any	optional	Optional MedDRA reaction term to filter by (e.g. "headache", "nausea").
`date_from`	any	optional	Start date filter in YYYYMMDD format (e.g. "20200101").
`date_to`	any	optional	End date filter in YYYYMMDD format (e.g. "20221231").
`limit`	integer	optional	Number of reports to return (1–100, default 10). (default: `10`)

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

import httpx

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

`get_drug_label`

Fetch FDA-approved drug label for a medication. Returns the full label content including indications, contraindications, warnings, dosage instructions, and known adverse reactions. Args: drug_name: Brand name (e.g. "Advil") or generic name (e.g. "ibuprofen"). Returns: Drug label sections from the FDA SPL database. Text fields truncated at 2,000 chars. Returns found=false if no label found.

Parameter	Type	Required	Description
`drug_name`	string	required	Brand name (e.g. "Advil") or generic name (e.g. "ibuprofen").

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

import httpx

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

`search_enforcement`

Search FDA enforcement actions — recalls, market withdrawals, and safety alerts. Args: product_type: Product category — "drug", "food", or "device" (default "drug"). date_from: Start date of recall initiation in YYYYMMDD format. date_to: End date of recall initiation in YYYYMMDD format. classification: Recall classification — "Class I" (most serious), "Class II", or "Class III". limit: Number of actions to return (1–100, default 10). Returns: Dictionary with count and enforcement actions (recall number, reason, classification, recalling firm). Class I = most serious (risk of serious adverse health consequences).

Parameter	Type	Required	Description
`product_type`	string	optional	Product category — "drug", "food", or "device" (default "drug"). (default: `drug`)
`date_from`	any	optional	Start date of recall initiation in YYYYMMDD format.
`date_to`	any	optional	End date of recall initiation in YYYYMMDD format.
`classification`	any	optional	Recall classification — "Class I" (most serious), "Class II", or "Class III".
`limit`	integer	optional	Number of actions to return (1–100, default 10). (default: `10`)

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

import httpx

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

`device_adverse_events`

Search FDA medical device adverse event reports (MAUDE database). Args: device_name: Device brand name (e.g. "pacemaker", "insulin pump", "hip implant"). event_type: Filter by event type — "Malfunction", "Injury", "Death", or "No apparent adverse event". date_from: Start date filter in YYYYMMDD format. date_to: End date filter in YYYYMMDD format. limit: Number of reports to return (1–100, default 10). Returns: Dictionary with count and device adverse event reports (device name, manufacturer, event type, narrative description). Sourced from MAUDE database.

Parameter	Type	Required	Description
`device_name`	string	required	Device brand name (e.g. "pacemaker", "insulin pump", "hip implant").
`event_type`	any	optional	Filter by event type — "Malfunction", "Injury", "Death", or "No apparent adverse event".
`date_from`	any	optional	Start date filter in YYYYMMDD format.
`date_to`	any	optional	End date filter in YYYYMMDD format.
`limit`	integer	optional	Number of reports to return (1–100, default 10). (default: `10`)

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

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/openfda/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'device_name': 'pacemaker'},
            'name': 'device_adverse_events'}},
)
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/openfda/" \
  -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/openfda/",
    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_adverse_events to find items, then get_drug_label 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 OpenFDA provide?

FDA data — drug adverse events, product recalls, and medical device reports. It exposes 5 tools: search_adverse_events, get_drug_label, search_enforcement, device_adverse_events, 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 OpenFDA API return?

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