Tutorial: ClinicalTrials.gov

Science

Data source: ClinicalTrials.gov

Overview

ClinicalTrials.gov wraps ClinicalTrials.gov, 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-clinicaltrials": {
      "url": "https://context.gnist.ai/mcp/clinicaltrials/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`search_trials`

Search ClinicalTrials.gov for clinical trials with flexible filters. Covers 500K+ registered clinical trials worldwide. Returns trial summaries including NCT ID, title, status, phase, conditions, interventions, and sponsor. Args: query: General search term (searches all fields). Examples: "aspirin heart", "mRNA vaccine", "CRISPR gene therapy". condition: Filter by condition or disease. Examples: "diabetes", "breast cancer", "Alzheimer's disease", "COVID-19". intervention: Filter by intervention/treatment. Examples: "pembrolizumab", "cognitive behavioral therapy", "radiation". status: Filter by trial status. One of: RECRUITING, NOT_YET_RECRUITING, ACTIVE_NOT_RECRUITING, COMPLETED, TERMINATED, WITHDRAWN, SUSPENDED, ENROLLING_BY_INVITATION, UNKNOWN. phase: Filter by trial phase. One of: EARLY_PHASE1, PHASE1, PHASE2, PHASE3, PHASE4, NA. sponsor: Filter by sponsor organization. Examples: "Pfizer", "NIH", "Mayo Clinic". max_results: Number of results to return (1-50, default 10). Returns: List of trial summaries with nct_id, brief_title, overall_status, phase, conditions, interventions, sponsor, start_date, enrollment.

Parameter	Type	Required	Description
`query`	any	optional	General search term (searches all fields). Examples: "aspirin heart", "mRNA vaccine", "CRISPR gene therapy".
`condition`	any	optional	Filter by condition or disease. Examples: "diabetes", "breast cancer", "Alzheimer's disease", "COVID-19".
`intervention`	any	optional	Filter by intervention/treatment. Examples: "pembrolizumab", "cognitive behavioral therapy", "radiation".
`status`	any	optional	Filter by trial status. One of: RECRUITING, NOT_YET_RECRUITING, ACTIVE_NOT_RECRUITING, COMPLETED, TERMINATED, WITHDRAWN, SUSPENDED, ENROLLING_BY_INVITATION, UNKNOWN.
`phase`	any	optional	Filter by trial phase. One of: EARLY_PHASE1, PHASE1, PHASE2, PHASE3, PHASE4, NA.
`sponsor`	any	optional	Filter by sponsor organization. Examples: "Pfizer", "NIH", "Mayo Clinic".
`max_results`	integer	optional	Number of results to return (1-50, default 10). (default: `10`)

curl -X POST "https://context.gnist.ai/mcp/clinicaltrials/" \
  -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": {"query": "renewable energy"}}}'

import httpx

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

`get_trial`

Get detailed information about a specific clinical trial by NCT ID. Returns comprehensive trial details including title, summary, status, phase, conditions, interventions, sponsor, eligibility criteria, outcomes, and locations. Args: nct_id: ClinicalTrials.gov NCT identifier (e.g., "NCT03367897", "NCT04368728"). Found in search_trials results or on clinicaltrials.gov. Returns: Full trial record with nct_id, brief_title, official_title, brief_summary, overall_status, phase, study_type, conditions, interventions (name/type/description), sponsor, collaborators, start_date, completion_date, enrollment, eligibility_criteria, primary_outcomes, locations.

Parameter	Type	Required	Description
`nct_id`	string	required	ClinicalTrials.gov NCT identifier (e.g., "NCT03367897", "NCT04368728"). Found in search_trials results or on clinicaltrials.gov.

curl -X POST "https://context.gnist.ai/mcp/clinicaltrials/" \
  -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/clinicaltrials/",
    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())

`get_trials_by_condition`

Find clinical trials studying a specific condition or disease. Shortcut for search_trials with condition filter pre-set. Useful for quickly finding all trials for a disease. Args: condition: The condition or disease to search for. Examples: "lung cancer", "type 2 diabetes", "major depressive disorder", "rheumatoid arthritis". status: Optional status filter. One of: RECRUITING, NOT_YET_RECRUITING, ACTIVE_NOT_RECRUITING, COMPLETED, TERMINATED, WITHDRAWN, SUSPENDED, ENROLLING_BY_INVITATION, UNKNOWN. max_results: Number of results to return (1-50, default 10). Returns: List of trial summaries matching the condition.

Parameter	Type	Required	Description
`condition`	string	required	The condition or disease to search for. Examples: "lung cancer", "type 2 diabetes", "major depressive disorder", "rheumatoid arthritis".
`status`	any	optional	Optional status filter. One of: RECRUITING, NOT_YET_RECRUITING, ACTIVE_NOT_RECRUITING, COMPLETED, TERMINATED, WITHDRAWN, SUSPENDED, ENROLLING_BY_INVITATION, UNKNOWN.
`max_results`	integer	optional	Number of results to return (1-50, default 10). (default: `10`)

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

import httpx

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

`get_trials_by_sponsor`

Find clinical trials run by a specific sponsor organization. Useful for investigating a company's drug pipeline or an institution's research portfolio. Args: sponsor: Sponsor organization name. Examples: "Pfizer", "Novartis", "National Cancer Institute", "Mayo Clinic", "Roche". status: Optional status filter. One of: RECRUITING, NOT_YET_RECRUITING, ACTIVE_NOT_RECRUITING, COMPLETED, TERMINATED, WITHDRAWN, SUSPENDED, ENROLLING_BY_INVITATION, UNKNOWN. max_results: Number of results to return (1-50, default 10). Returns: List of trial summaries from the specified sponsor.

Parameter	Type	Required	Description
`sponsor`	string	required	Sponsor organization name. Examples: "Pfizer", "Novartis", "National Cancer Institute", "Mayo Clinic", "Roche".
`status`	any	optional	Optional status filter. One of: RECRUITING, NOT_YET_RECRUITING, ACTIVE_NOT_RECRUITING, COMPLETED, TERMINATED, WITHDRAWN, SUSPENDED, ENROLLING_BY_INVITATION, UNKNOWN.
`max_results`	integer	optional	Number of results to return (1-50, default 10). (default: `10`)

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

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/clinicaltrials/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'sponsor': 'example'},
            'name': 'get_trials_by_sponsor'}},
)
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/clinicaltrials/" \
  -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/clinicaltrials/",
    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_trials to find items, then get_trial 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.

FAQ

What data does ClinicalTrials.gov provide?

Search clinical trial registrations — study details, conditions, interventions, and status. It exposes 5 tools: search_trials, get_trial, get_trials_by_condition, get_trials_by_sponsor, 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 ClinicalTrials.gov API return?

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