Python Version Tests License: MIT

The Program Integrity Alliance (PIA) aims to make working with U.S. Government datasets easier and AI-friendly. We have ingested hundreds of thousands of documents and articles across a range of sources, and this list is growing. This MCP server enables AIs to search this data at a more detailed level than on most source websites, for example, searching within PDF reports to find the exact pages where text and images appear.

Full attribution is given to the amazing open federal data sources, and all links in the data provided by PIA will always direct back to the original source.

Currently, the list of datasets includes:

1. U.S. Government Accountability Office (GAO) - 10k Federal Reports since 2010 and 5.5k Open Oversight Recommendations
2. Oversight.gov - 28k OIG Federal Reports since 2010, and 29k Open Oversight Recommendations
3. U.S. Congress - Bill texts for sessions 118 and 119
4. Department of Justice (DOJ) - 195k Press Releases since 2000
5. Federal Agency annual reports - Congressional Justification, Financial Report, Performance Report - 139 reports across 10 priority agencies, with best coverage in 2024.
6. All Congression Research Service reports - 22k reports provided by EveryCRSReport.com
7. U.S. Presidential Executive Orders - Order for the last 7 presidencies as provided by the Federal Register.

This data is updated weekly, and we will be adding more datasets and tools soon.

If you have any questions, or requests for other datasets, we look forward to hearing from you by raising an issue here.

For more information on how to use PIA's MCP resources in platforms like Claude and ChatGPT, see PIA Connect.

✨ Core Features

• 🔎 Document Search: Query PIA database with comprehensive OData filtering options
• 📊 Faceted Search: Discover available filter fields and values
• 📝 AI Instruction Prompts: Prompts that instruct LLMs on how to summarize search results and use search tools

🚀 Quick Start

Getting a PIA API Key

1. Go to https://programintegrity.org/ and register for a free PIA account (or log in if you already have one)
2. Once logged in, click the user icon (top right) and choose API/MCP key (this opens the API / MCP Keys page at /account/api-keys)
3. Generate a new key, then copy it — you'll provide it to the MCP server via the X-API-KEY header / --api-key argument

Installing using Docker MCP Toolkit (Recommended)

1. Download and run the latest version of Docker Desktop
2. Navigate to 'MCP Toolkit'
3. Search for 'Program Integrity Alliance'
4. Add as a server by clicking '+'
5. Under 'Configuration' enter your key
6. In 'MCP Toolkit' navigate to 'Clients'
7. Choose one, eg 'Claude Desktop'
8. Start your Client
9. You should now see 'pia_search' and other tools

Installing via Smithery

To install PIA Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install pia-mcp-server --client claude

Installing Manually

Install using uv:

uv tool install pia-mcp-server

Refreshing Tool Specs (No API Key Needed for Listing)

Tool listing in this local server is served from a local snapshot, so tools are discoverable even without an API key. To refresh the snapshot from the remote server, run:

PIA_API_KEY=your_key python utils/refresh_tools.py

For development:

# Clone and set up development environment
git clone https://github.com/Program-Integrity-Alliance/pia-mcp-local.git
cd pia-mcp-local

# Create and activate virtual environment
uv venv
source .venv/bin/activate

# Install with test dependencies
uv pip install -e ".[test]"

For Docker:

# Build the Docker image if you want to use a local image
git clone https://github.com/Program-Integrity-Alliance/pia-mcp-local.git
cd pia-mcp-local
docker build -t pia-mcp-server:latest .

🔌 MCP Integration

Add this configuration to your MCP client config file:

{
    "mcpServers": {
        "pia-mcp-server": {
            "command": "uv",
            "args": [
                "tool",
                "run",
                "pia-mcp-server",
                "--api-key", "YOUR_API_KEY"
            ],
            "cwd": "/path/to/your/pia-mcp-local"
        }
    }
}

For Docker:

You must build the Docker image ...

docker build -t pia-mcp-server:latest .

Then add this to your Client, eg Claude ...

{
    "mcpServers": {
        "pia-mcp-server": {
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-i",
                "pia-mcp-server:latest",
                "--api-key", "YOUR_API_KEY"
            ]
        }
    }
}

💡 Available Tools

The server provides 2 tools, forwarded verbatim to the Program Integrity Alliance (PIA) MCP server:

1. pia_search

Purpose: Primary search over the PIA database of government oversight reports, recommendations, and related documents.

Description: Returns ranked results with snippets, citations, embedded facets, and a govquery_url, with full OData filtering. Consolidates the former per-dataset and agency-specific search tools into one.

Parameters:

• query (required): Search query text
• filter (optional): OData filter expression supporting complex boolean logic
• Additional optional paging / facet / mode parameters — see the tool's inputSchema

2. pia_oversight_recommendations

Purpose: Search the Open Recommendations dataset (GAO + Oversight.gov) with facets enabled by default.

Parameters:

• query (required): Search query text
• filter (optional): OData filter expression

The remote also exposes search and fetch (OpenAI ChatGPT MCP spec) — this proxy intentionally does not expose them; use pia_search instead. They are excluded by the sync script (utils/refresh_tools.py).

Search Modes

pia_search supports OData filtering and faceting. The filter parameter uses standard OData query syntax.

Example Filter Expressions:

• Basic filter: "SourceDocumentDataSource eq 'GAO'"
• Multiple conditions: "SourceDocumentDataSource eq 'GAO' or SourceDocumentDataSource eq 'Oversight.gov'"
• Complex grouping: "SourceDocumentDataSource eq 'GAO' and RecStatus ne 'Closed'"
• Negation: "SourceDocumentDataSource ne 'Department of Justice' and not (RecStatus eq 'Closed')"
• List membership: "IsIntegrityRelated eq 'Yes' and RecPriorityFlag in ('High', 'Critical')"
• Date ranges: "SourceDocumentPublishDate ge '2020-01-01' and SourceDocumentPublishDate le '2024-12-31'"
• Boolean grouping: "(SourceDocumentDataSource eq 'GAO' or SourceDocumentDataSource eq 'Oversight.gov') and RecStatus eq 'Open'"

OData Filter Operators:

• eq - equals: field eq 'value'
• ne - not equals: field ne 'value'
• gt - greater than: amount gt 1000
• ge - greater than or equal: date ge '2023-01-01'
• lt - less than: amount lt 5000
• le - less than or equal: date le '2023-12-31'
• in - value in list: status in ('Active', 'Pending')

OData Logical Operators:

• and - logical AND: field1 eq 'value' and field2 gt 100
• or - logical OR: status eq 'Active' or status eq 'Pending'
• not - logical NOT: not (status eq 'Inactive')
• () - grouping: (field1 eq 'A' or field1 eq 'B') and field2 gt 0

OData String Functions:

• contains(field, 'text') - field contains text
• startswith(field, 'prefix') - field starts with prefix
• endswith(field, 'suffix') - field ends with suffix

2. PIA Search Facets

Discover available field names and values for filtering.

Tool Name: pia_search_facets

Parameters:

• query (optional): Optional query to get facets for (default: "")

Purpose:

• Discover available field names (e.g., data_source, document_type, agency)
• Find possible field values (e.g., "OIG", "GAO", "audit_report")
• Understand data types for each field (string, date, number)

This information helps you construct proper filter expressions for the search tools.

🔍 Filter Discovery Workflow

To effectively use OData filters, follow this workflow:

Step 1: Discover Available Fields

Use the pia_search_facets tool to explore what fields are available for filtering. You can provide a query to get facets relevant to your search topic, or omit the query to see all available fields.

Step 2: Examine Field Values

The facets response will show available fields and their possible values:

{
  "SourceDocumentDataSource": ["Oversight.gov", "GAO", "CMS", "FBI"],
  "RecStatus": ["Open", "Closed", "In Progress"],
  "RecPriorityFlag": ["High", "Medium", "Low", "Critical"],
  "IsIntegrityRelated": ["Yes", "No"],
  "SourceDocumentPublishDate": "2020-01-01 to 2024-12-31"
}

Step 3: Build Targeted Search

Use the pia_search tool with discovered fields to create precise OData filters:

Basic Example:

Query: "Medicare fraud"
Filter: "SourceDocumentDataSource eq 'GAO' and SourceDocumentPublishDate ge '2023-01-01' and IsIntegrityRelated eq 'Yes'"

Complex Example:

Query: "healthcare violations"
Filter: "(SourceDocumentDataSource eq 'Oversight.gov' or SourceDocumentDataSource eq 'CMS') and RecPriorityFlag in ('High', 'Critical') and SourceDocumentPublishDate ge '2023-01-01'"

📝 AI Instruction Prompts

The server exposes one prompt that instructs the calling LLM how to use the PIA tools and format responses:

pia_assistant_guidance

Comprehensive guidance for an LLM using the PIA (GovQuery) tools: search strategy, citation format, and response structure.

Arguments: None (reusable guidance)

⚙️ Configuration

The API key is always provided via the MCP server configuration. Additional settings can be configured through environment variables:

Variable	Purpose	Default
PIA_API_URL	PIA API endpoint	https://www.programintegrity.org/mcp
REQUEST_TIMEOUT	API request timeout (seconds)	60
MAX_RESULTS	Maximum results per query	50

MCP Configuration

The API key must be provided in your MCP client configuration using the --api-key argument. See Getting a PIA API Key above to create one.

{
    "mcpServers": {
        "pia-mcp-server": {
            "command": "pia-mcp-server",
            "args": ["--api-key", "YOUR_API_KEY"]
        }
    }
}

Replace YOUR_API_KEY with your actual PIA API key.

🧪 Testing

Run the test suite:

python -m pytest

Run with coverage:

python -m pytest --cov=pia_mcp_server

📄 License

Released under the MIT License. See the LICENSE file for details.

---