Tutorial: Hospital Directory

Health

Data source: Curated dataset (CMS, AHA)

Overview

Hospital Directory wraps Curated dataset (CMS, AHA), handling authentication, pagination, and rate limits for you. This tutorial covers all 10 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-hospital-directory": {
      "url": "https://context.gnist.ai/mcp/hospital-directory/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (10)

`get_hospital`

Get detailed information about a hospital. Returns name, location, type, beds, trauma level, specialties, and accreditation.

Parameter	Type	Required	Description
`hospital_id`	string	required	Hospital ID slug (e.g. mayo-clinic-rochester, johns-hopkins).

curl -X POST "https://context.gnist.ai/mcp/hospital-directory/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_hospital", "arguments": {"hospital_id": "mayo-clinic-rochester"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/hospital-directory/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'hospital_id': 'mayo-clinic-rochester'},
            'name': 'get_hospital'}},
)
print(resp.json())

`search_hospitals`

Search the hospital directory.

Parameter	Type	Required	Description
`query`	string	required	Search by name, city, or specialty.
`limit`	integer	optional	(default: `20`)

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

import httpx

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

`list_hospitals_by_state`

List hospitals in a US state.

Parameter	Type	Required	Description
`state`	string	required	US state abbreviation (e.g. MA, CA, NY).
`limit`	integer	optional	(default: `50`)

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

import httpx

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

`list_hospitals_by_type`

List hospitals by type.

Parameter	Type	Required	Description
`hospital_type`	string	required	Hospital type (Teaching, General, Children's, VA).
`limit`	integer	optional	(default: `50`)

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

import httpx

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

`list_hospitals_by_specialty`

List hospitals with a given medical specialty.

Parameter	Type	Required	Description
`specialty`	string	required	Medical specialty (e.g. Cardiology, Oncology, Neurology).
`limit`	integer	optional	(default: `50`)

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

import httpx

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

`list_trauma_centers`

List trauma centers by level.

Parameter	Type	Required	Description
`level`	string	optional	(default: `Level I`)
`limit`	integer	optional	(default: `50`)

curl -X POST "https://context.gnist.ai/mcp/hospital-directory/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_trauma_centers", "arguments": {"level": "Level I"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/hospital-directory/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'level': 'Level I'}, 'name': 'list_trauma_centers'}},
)
print(resp.json())

`get_hospital_states`

List all US states with hospitals in the directory.

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

import httpx

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

`get_hospital_types`

List all hospital types in the directory.

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

import httpx

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

`get_medical_specialties`

List all medical specialties in the directory.

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

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/hospital-directory/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {}, 'name': 'get_medical_specialties'}},
)
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/hospital-directory/" \
  -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/hospital-directory/",
    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_hospitals to find items, then get_hospital 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 Hospital Directory provide?

US hospital directory — beds, trauma level, specialties, accreditation for major hospitals. It exposes 10 tools: get_hospital, search_hospitals, list_hospitals_by_state, list_hospitals_by_type, list_hospitals_by_specialty, list_trauma_centers, get_hospital_states, get_hospital_types, get_medical_specialties, 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 Hospital Directory API return?

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

Next Steps

Interactive Playground

Try tools in your browser — no setup required.

Full Reference

Complete docs for all 10 tools.

Getting Started with Hospital Directory