Jump to section

API Reference · v1.0

contextRx.ai
API Documentation

Real-time, inference-ready clinical context delivered to AI agents via the Model Context Protocol. Seven tools. Two query paths. One endpoint.

Overview

contextRx.ai is a Context-as-a-Service platform built on the Model Context Protocol (MCP). Your AI agent connects to a single endpoint and calls tools by name. The platform handles provider routing, identity resolution, enrichment, caching, consent enforcement, and metering automatically.

ℹ️

The platform exposes 7 MCP tools across two query paths — member-level (3 tools) and population-level (4 tools). Query routing is automatic based on the parameters your agent passes. No separate endpoints, no configuration required.

Quick Start
# Connect your MCP client to the contextRx endpoint
endpoint: https://www.contextrx.ai/mcp
auth:     X-API-Key: crx_live_your_key_here

# Call any tool by name — routing is automatic
get_member_context(member_id="mbr_12345")
get_cohort_brief(cohort_id="chrt_medicare_q1")

Authentication

All requests require an API key passed in the X-API-Key header. API keys are issued when you sign up at contextrx.ai/signup. Keys are prefixed with crx_live_ for production and crx_test_ for sandbox.

Authentication Header
X-API-Key: crx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️

Never expose your API key in client-side code or commit it to version control. All production API calls must originate from your server-side application.

MCP Endpoint

The platform exposes a single MCP-compatible SSE endpoint. Connect any MCP client — Claude, LangChain, a custom agent — using the URL and your API key.

Property	Value
Endpoint URL	`https://www.contextrx.ai/mcp`
Protocol	MCP over SSE (Server-Sent Events)
Auth header	`X-API-Key`
Schema version	`1.0` — included in every response
Sandbox endpoint	`https://www.contextrx.ai/sandbox/demo`

Automatic Query Routing

The platform automatically routes every tool call to the correct pipeline based on the parameters passed. Member-level tools receive a member_id. Population-level tools receive a cohort_id or no member identifier. No configuration required.

Path	Triggered by	Cache TTL	Billing	PHI exposure
Member-level	`member_id` parameter present	4 hours	Per call	Hashed identifiers only
Population-level	Cohort or aggregate tool called	24 hours	Single cohort event	None — aggregate only

✓

Cache hits do not generate billing events. If the same member context is requested within the 4-hour TTL window, the cached response is returned at no charge. Consent is re-verified on every cache hit.

Rate Limits

Rate limits are enforced per customer using a Redis token bucket. Limits are tier-based and reset continuously rather than on a fixed window.

Tier	Requests/second	Burst	Response on limit
Standard	2 rps	5	`429 Too Many Requests`
Professional	10 rps	20	`429 Too Many Requests`
Enterprise	30 rps	60	`429 Too Many Requests`

Member-Level Tools

These three tools operate on a single identified member. Pass a member_id and the platform resolves identity, selects providers based on insurance type, runs the enrichment pipeline, and returns structured clinical context.

get_member_context

Retrieves enriched clinical context for a single health plan member. Returns medication fills, drug interactions, lab results, risk score, intervention type, and human review flags. Use this as the primary tool for MTM sessions, care management, and clinical decision support.

Member-level 4hr cache

Parameters

Parameter	Type	Required	Description
member_id	string	required	Your internal member identifier. Resolved against provider identity graphs.
include	string[]	optional	Subset of capabilities to include. Options: `medications`, `labs`, `encounters`, `drug_interactions`, `risk_score`, `hcp_profile`. Defaults to all.
idempotency_key	string	optional	Same key within 60 seconds returns cached response with one billing event only.
customer_id	string	optional	Override customer context for multi-tenant deployments.

Example Request

MCP Tool Call
get_member_context({
  member_id: "mbr_12345",
  include: ["medications", "drug_interactions", "risk_score"],
  idempotency_key: "session_abc_001"
})

Response Schema

{ "member_id": "341d976a44aae56f", // hashed "risk_score": 0.87, "intervention_type": "urgent_mtm", "findings": [ { "type": "drug_interaction", "severity": "high", "description": "warfarin + aspirin interaction", "recommended_action": "pharmacist_review" } ], "data_completeness": 0.92, "missing_sources": [], "requires_human_review": true, "human_review_reasons": ["high_risk_score"], "next_action": { "type": "escalate_to_pharmacist", "confidence_warning": false }, "schema_version": "1.0", "call_id": "ctx_d1451b881a4b", "served_from_cache": false, "computed_at": "2026-04-07T02:05:50Z" }

get_hcp_context

Returns enriched provider context for a healthcare professional identified by NPI. Includes prescribing volume, drug class patterns, Open Payments financial relationships, and Medicare Part D prescribing data. Use for prior authorization support, network analysis, and detailing prioritization.

Member-level 4hr cache

Parameter	Type	Required	Description
npi	string	required	10-digit National Provider Identifier.
include_payments	boolean	optional	Include Open Payments financial relationship data. Defaults to true.
idempotency_key	string	optional	Deduplication key for retry-safe calls.

flag_drug_interactions

Checks a list of RxCUI drug identifiers against the RxNorm interaction database and openFDA adverse event data. Returns severity-ranked interaction flags with recommended actions. Use before any medication counseling session or when a new prescription is added to a member's regimen.

Member-level 4hr cache

Parameter	Type	Required	Description
rxcuis	string[]	required	List of RxCUI identifiers for the drugs to check. Minimum 2, maximum 20.
member_id	string	optional	If provided, cross-references against the member's known medication list.
severity_threshold	string	optional	Return only interactions at or above this severity. Options: `low`, `moderate`, `high`. Defaults to `low`.

Population-Level Tools

These four tools operate on cohorts and populations. No individual PHI is exposed — all results are aggregated. Results are cached for 24 hours and billed as a single cohort event regardless of population size.

get_cohort_brief

Returns a high-level summary of a cohort — risk distribution, mean adherence (PDC), top drug interaction pairs, and intervention opportunity sizing. Use for population health dashboards, care management prioritization, and executive reporting.

Population-level 24hr cache

Parameter	Type	Required	Description
cohort_id	string	required	Identifier for the cohort as defined in your customer configuration.
as_of_date	string	optional	ISO 8601 date for point-in-time cohort snapshot. Defaults to today.
idempotency_key	string	optional	Deduplication key.

Response Schema

{ "cohort_id": "chrt_medicare_q1", "cohort_size": 12400, "risk_distribution": { "high": 0.18, "medium": 0.41, "low": 0.41 }, "mean_pdc": 0.74, "top_ddi_pairs": [ { "drugs": ["warfarin", "aspirin"], "prevalence": 0.08 } ], "intervention_opportunities": 2232, "schema_version": "1.0" }

get_population_analytics

Returns detailed analytics across a population including drug class adherence trends, risk score distribution over time, and condition prevalence. Suited for actuarial models, value-based contract reporting, and network performance analysis.

Population-level 24hr cache

Parameter	Type	Required	Description
cohort_id	string	required	Cohort identifier.
dimensions	string[]	optional	Analytics dimensions to include. Options: `adherence`, `risk_trend`, `condition_prevalence`, `ddi_prevalence`. Defaults to all.
period_months	integer	optional	Lookback period in months. Default 12, maximum 36.

compute_cohort_metrics

Runs full enrichment across a cohort in batches of 50 concurrent members and aggregates results. More detailed than get_cohort_brief — returns per-condition adherence rates, DDI prevalence by drug class, and risk stratification with intervention type breakdown. Use for deep population analysis and programme design.

Population-level 24hr cache

Parameter	Type	Required	Description
cohort_id	string	required	Cohort identifier.
metrics	string[]	optional	Specific metrics to compute. Defaults to full suite.
idempotency_key	string	optional	Recommended for large cohorts — prevents duplicate billing on retries.

ℹ️

For cohorts over 10,000 members this tool runs asynchronously. The initial call returns a job_id. Poll the status endpoint until status: complete, then retrieve results.

get_intervention_analytics

Returns programme performance metrics — intervention completion rates, cost reduction attribution, engagement outcomes, and ROI estimates. Use to measure the impact of care management programmes and demonstrate value to plan sponsors.

Population-level 24hr cache

Parameter	Type	Required	Description
programme_id	string	required	Identifier for the care management programme to analyze.
period	string	optional	Reporting period. Options: `q1`, `q2`, `q3`, `q4`, `ytd`, `custom`. Defaults to `ytd`.
include_roi	boolean	optional	Include cost reduction and ROI estimates. Defaults to true.

Error Codes

All errors return a JSON body with error, message, and call_id fields. Use the call_id when contacting support.

Status	Error	Meaning	Resolution
401	`unauthorized`	Missing or invalid API key	Check your `X-API-Key` header
400	`invalid_member`	member_id could not be resolved	Verify the member ID format matches your configuration
400	`consent_required`	Member has not consented for this provider	Complete the consent flow before calling this tool
429	`rate_limit_exceeded`	Request rate exceeds your tier limit	Implement exponential backoff. Check `Retry-After` header
422	`spend_cap_reached`	Customer spend cap has been hit	Increase spend cap in admin UI or wait for reset
503	`provider_unavailable`	Upstream provider API is down	Response includes partial data from available providers. `next_action` field guides agent behaviour

Consent & HIPAA

The platform enforces per-provider consent gates. Some providers (Surescripts, Particle Health, Health Gorilla) require individual member consent before data can be retrieved. Others (RxNorm, openFDA, NPI) are public data sources that do not require consent.

⚠️

Your organisation must have a signed BAA with contextRx.ai before accessing any PHI-adjacent data. BAA is included in Professional and Enterprise tiers. Sign up to get started.

Provider	Consent required	Consent type
RxNorm, openFDA, NPI, ClinicalTrials	No	Public data — no consent needed
CMS Blue Button	Yes	Medicare beneficiary OAuth flow
CMS BCDA	No	Organisation-level ACO/SSP access
Surescripts, Particle Health, Health Gorilla	Yes	TEFCA or customer-specific consent

Billing Model

Billing is per MCP tool call, metered in real time through Lago. Cache hits within the TTL window are free. Each customer can configure a monthly spend cap — the platform enforces hard stops or grace periods based on your configuration.

Tier	Rate	Cache hits	Spend caps
Standard	$0.05 / call	Free	Configurable in admin UI
Professional	$0.03 / call	Free	Hard stop or grace period
Enterprise	Custom	Free	Custom SLA

Sandbox & Testing

The sandbox endpoint returns real enrichment responses using synthetic test patients. No API key required for the sandbox demo. Use crx_test_ prefixed keys for automated testing against the full API with synthetic data.

Patient	member_id	Profile
Dorothy	`synthea_dorothy`	Elderly Medicare patient, multiple chronic conditions, polypharmacy risk
James	`synthea_james`	Middle-aged, diabetes + hypertension, adherence gaps
Sandra	`synthea_sandra`	Commercial plan member, asthma, recent ER visit

✓

Try the interactive demo to see live enrichment responses for all three synthetic patients without any setup.

Sandbox Quick Test
# Test the sandbox endpoint — no API key needed
curl -s https://www.contextrx.ai/sandbox/demo | python3 -m json.tool

# Test with a synthetic patient via the full API
curl -s https://www.contextrx.ai/api/v1/context \
  -H "X-API-Key: crx_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"member_id": "synthea_dorothy"}'

Ready to integrate?

Get your API key in under 2 minutes. The sandbox is available immediately — no credit card required to start testing.

Get API Access Try the Demo

contextRx.aiAPI Documentation

Overview

Authentication

MCP Endpoint

Automatic Query Routing

Rate Limits

Member-Level Tools

Population-Level Tools

Error Codes

Consent & HIPAA

Billing Model

Sandbox & Testing

contextRx.ai
API Documentation