# HHS Open Payments MCP > HHS Open Payments provides direct access to the HHS Open Payments database for financial transparency in healthcare. It lets users search records for specific physicians or teaching hospitals and analyze payment data made by drug and device companies. You can list available datasets, download raw data structures (CSV, JSON), run precise queries using SoQL, and inspect metadata about the underlying public health records. ## Overview - **Category:** government-public-data - **Price:** Free - **Tags:** financial-transparency, healthcare-data, compliance, public-records, data-analysis ## Description This MCP connects your agent to the HHS Open Payments database, letting you audit financial relationships across the healthcare industry. Instead of browsing complex government portals, you can ask for specific details—like payment amounts or connections between a specialist and a major hospital—and get structured results back immediately. You'll find tools to list all available datasets and download them in CSV, JSON, or XML formats for your reports. Need to narrow down the scope? You can search specifically for physicians or teaching hospitals by name. For complex analysis, you use advanced querying features that filter records precisely using SoQL. When you connect this MCP via Vinkius, it acts as a single gateway, giving any compatible client access to all these public record tools without needing separate API keys for every function. ## Tools ### download_dataset Downloads a specified Open Payments dataset file in CSV, JSON, or XML format. ### get_dataset Retrieves the metadata and structure details for a specific Open Payments dataset. ### list_datasets Lists all available datasets within the Open Payments database. ### query_dataset Runs targeted queries against a dataset, allowing filtering and sorting using SoQL. ### search_hospitals Searches the database to find records associated with specific teaching hospitals. ### search_physicians Finds and retrieves records for specific medical providers by name. ## Prompt Examples **Prompt:** ``` List all available Open Payments datasets. ``` **Response:** ``` I've retrieved the list of available datasets. There are several active datasets including 'General Payments 2023' (ID: pgaw-6u8r) and 'Research Payments 2023' (ID: 5930-21ab). Which one would you like to explore? ``` **Prompt:** ``` Search for physicians named 'Gregory House' in the database. ``` **Response:** ``` Searching for 'Gregory House'... I found 2 matching records. One is a specialist in Infectious Diseases in New Jersey. Would you like to see the payment summary for this physician? ``` **Prompt:** ``` Query dataset pgaw-6u8r for payments in Florida where the amount is over $5,000. ``` **Response:** ``` Executing query on dataset pgaw-6u8r... I found 12 records matching your criteria. The largest payment was $15,400 to a teaching hospital in Miami. Should I list the top 5 results? ``` ## Capabilities ### Discover available data sets List and inspect the metadata of all Open Payments datasets. ### Get dataset structure details Fetch detailed information about a specific dataset to understand its column names and format. ### Query records with filters Run complex queries on a specified dataset, filtering results using SoQL syntax. ### Search for medical providers Find specific physicians within the database by name. ### Search for hospitals Locate records associated with specific teaching hospitals. ### Export raw data files Download a specified Open Payments dataset in CSV, JSON, or XML format. ## Use Cases ### Verifying corporate influence on local care A journalist needs to know if a major drug company paid multiple providers in one county. They use `list_datasets` to find the right payments pool, then run `query_dataset`, filtering by the specific county and payment year. The agent returns a clean list of all implicated doctors. ### Compliance review for mergers A compliance officer must verify that newly acquired hospitals follow reporting standards. They use `search_hospitals` to find records tied to the new facility, and then `get_dataset` to check the required data fields before exporting everything via `download_dataset`. ### Investigating a malpractice pattern A researcher suspects a specific doctor is involved in multiple high-value payments. They use `search_physicians` to isolate that individual, and then they run a targeted query using `query_dataset` against the payment dataset for that person's name. ### Building a custom data dashboard A data scientist needs all historical records on payments. They use `list_datasets` to confirm the correct pool, and then run multiple targeted queries using `query_dataset` across different time ranges to pull structured results for their model. ## Benefits - You bypass manual portal navigation. Instead of clicking through multiple government tabs, you ask your agent to `list_datasets` and immediately see every available data pool for analysis. - Complex data filtering becomes simple. Forget writing complicated SQL joins; use `query_dataset` to filter records using SoQL right from your prompt, giving you immediate answers on payment amounts or locations. - Get the raw files when needed. If your team requires the full dataset—say, a CSV of all 2023 payments—you can reliably download it using `download_dataset` for external reporting. - Focus your search immediately. Need to verify an entity? Use `search_physicians` or `search_hospitals` to narrow down millions of records instantly and get the core record details you need, cutting research time from hours to minutes. - Understand the data structure first. Before querying, use `get_dataset` to inspect the metadata. This ensures your agent knows exactly which columns exist so you don't run a query that fails because of bad syntax. ## How It Works The bottom line is that you guide your agent through this sequence: discover what's available, check its structure, and then ask it to find exactly what you need. 1. First, request the list of all available datasets using `list_datasets` to determine which data pool you need. 2. Next, either use `get_dataset` to check the metadata and schema of that dataset or run a focused search for specific entities like hospitals via `search_hospitals`. 3. Finally, execute your analysis by running a query using `query_dataset`, specifying filters (SoQL), or downloading the raw data with `download_dataset`. ## Frequently Asked Questions **How do I find out what data fields are available using HHS Open Payments?** You use `get_dataset` to retrieve metadata for a specific pool. This function shows you every column name, its definition, and whether it's a text or numeric field before you write any query. **Can I search for both doctors and hospitals with HHS Open Payments?** Yes. You use `search_physicians` to find specific medical providers and `search_hospitals` to locate teaching facilities, pulling up records for both types of entities. **Is the data from HHS Open Payments real-time?** The MCP accesses historical datasets. Use `list_datasets` first to check the update timestamps and determine if a dataset contains the most recent payment years you need. **Do I need an API key for querying data with HHS Open Payments?** While not mandatory, providing an API Key is recommended. It helps increase your rate limit capacity when running repeated or high-volume queries using `query_dataset`. **What should I do if I run into rate limits when using `query_dataset`?** You must implement exponential backoff and retry logic. If your AI client hits a limit, the system will return a specific error code; wait several seconds before re-running the query until it succeeds. **What are the supported file formats when I use `download_dataset`?** You can request the data in CSV, JSON, or XML. For programmatic processing and reliability within your agent, JSON remains the recommended format for all exports. **How do I write complex filters or combine results using `query_dataset`?** You use standard Socrata Query Language (SoQL) syntax. You can filter by multiple fields and apply logical operators like AND, OR, and NOT to narrow down your search criteria. **After calling `list_datasets`, how do I figure out which dataset is right for my specific research needs?** You should use the `get_dataset` tool next. This retrieves detailed metadata, showing you exactly what columns and payment types each available Open Payments dataset contains. **Can I search for a specific doctor by name to see their financial records?** Yes! Use the `search_physicians` tool with the doctor's name. The agent will return matching profiles and their associated payment data from the Open Payments database. **How do I filter data for a specific state or payment amount?** You can use the `query_dataset` tool and provide a SoQL filter in the `where` parameter (e.g., `recipient_state = 'NY'` or `total_amount_of_payment_usdollars > 1000`). **What formats can I use to download the datasets?** The `download_dataset` tool supports 'csv', 'json', and 'xml' formats. JSON is generally recommended for programmatic access and AI analysis.