pubrecords

Halverson IQ Data

One paid MCP server for US public records, federal grants, and federal contracts. Companies, SEC filings, court dockets, spending awards, licenses, Grants.gov opportunities, and SAM.gov contract notices share a single API key and a single bill.

---

What this server includes

This repository is the combined Halverson IQ Data server.

Source	Tools
OpenCorporates, SEC EDGAR, CourtListener, USASpending, NPPES, FCC	Public-records tools (companies, filings, courts, spending, licenses, entity verification)
Grants.gov	Grant search, details, agency rollup, deadline radar
SAM.gov	Contract search, notice details, award notices

Not part of this server: business-intel and outdoor datasets (separate or retired), and web-page fetching (a different pipeline with its own fetchers and cache).

One customer key is checked on every tool. Free tier is 30 calls/day across the whole server. Pro is unlimited on the same key. Upgrade: https://mcpize.com/pubrecords-mcp

---

Pricing

Tier	Price	Limit
Free	$0	30 calls/day
Pro	$29/mo	Unlimited
Metered	$0.03/call	Pay-as-you-go

Keys are issued per user. Ask the operator for a key, or have them mint one with POST /admin/keys. Examples below use the placeholder YOUR_API_KEY.

---

Tool reference

Public records

Tool	Args	Returns
search_companies	name, state?, status?, limit?	OpenCorporates entities
get_company_details	company_id, jurisdiction	Officers, registered agent, filings
search_sec_filings	company_name, form_type?, date_from?, limit?	EDGAR filing list
get_sec_filing	accession_number	Filing metadata + index URL
search_court_cases	party_name, court?, date_from?, limit?	RECAP federal dockets
lookup_federal_spending	recipient_name, agency?, year?, limit?	USASpending awards
lookup_npi	name?, specialty?, state?, limit?	NPPES providers
get_ucc_filings	debtor_name, state	UCC liens (roadmap — see Data Gaps)
verify_entity	name, state?	Cross-source 0–100 confidence score
search_licenses	entity_name, license_type?, state?	NPI + FCC license union

Grants and federal contracts

Tool	Args	Returns
search_grants	keyword?, agency?, amount_min?, amount_max?, status?, limit?	Grants.gov opportunities
get_grant_details	opportunity_id	Full Grants.gov record
search_contracts	keyword?, naics_code?, agency?, set_aside?, limit?	SAM.gov solicitations
get_contract_details	notice_id	One SAM.gov notice
search_awards	recipient_name?, agency?, year?	SAM.gov award notices
get_agencies	type? (grants, contracts, or both)	Agencies with open opportunities
get_deadlines	days_ahead?	Grants closing inside the window
match_opportunities	org_description, org_type?, focus_areas?, limit?	Top grants + contracts for an org profile

focus_areas on the REST route is a comma-separated string. The MCP tool accepts a list.

Contract tools call SAM.gov only when SAM_API_KEY is set. If it is missing they return {"success": false, "error": "SAM_API_KEY is not configured"} and do not send a request.

---

Install in Claude

claude mcp add --transport http halverson-iq-data https://mcp-pubrecords-production.up.railway.app/mcp/

Note the trailing slash on /mcp/. Without it the gateway issues a 307 that drops the POST body, breaking the JSON-RPC handshake.

Then set the API key in your client:

X-API-Key: YOUR_API_KEY

---

Python SDK

A thin Python wrapper for non-MCP integrations lives in pubrecords-sdk/:

pip install pubrecords

from pubrecords import PubRecords

client = PubRecords(api_key="YOUR_API_KEY")
print(client.health())
print(client.search_companies(name="Apple", state="CA"))
print(client.search_grants(keyword="broadband"))

---

REST surface

Every MCP tool is also available over plain HTTP. Send the same X-API-Key on each call.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://mcp-pubrecords-production.up.railway.app/tools/search_companies?name=Apple&state=CA"

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://mcp-pubrecords-production.up.railway.app/tools/search_grants?keyword=broadband"

Production URL: https://mcp-pubrecords-production.up.railway.app

GET  /health                          (no auth)
GET  /usage                           (X-API-Key)
GET  /tools/<tool_name>?...           (X-API-Key)
POST /admin/keys                      (X-Admin-Token; fails closed)
POST /billing/upgrade                 (X-Admin-Token; fails closed)
POST /mcp/                            (MCP streamable-http transport)

GET /usage returns the remaining daily quota for that key. GET /health is unauthenticated.

Issuing a customer key

POST /admin/keys and POST /billing/upgrade return 403 unless PUBRECORDS_ADMIN_TOKEN is set and the X-Admin-Token header matches it. There is no default admin token.

curl -X POST https://mcp-pubrecords-production.up.railway.app/admin/keys \
  -H "X-Admin-Token: $PUBRECORDS_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"YOUR_API_KEY","tier":"free"}'

Promote that same key to the paid tier (this is the single billing switch):

curl -X POST https://mcp-pubrecords-production.up.railway.app/billing/upgrade \
  -H "X-Admin-Token: $PUBRECORDS_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"YOUR_API_KEY"}'

---

Local development

git clone https://github.com/bch1212/mcp-pubrecords.git
cd mcp-pubrecords
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn server:app --reload --port 8000

Run tests:

pytest -v

Environment variables (see .env.example):

Variable	Required	Purpose
PUBRECORDS_ADMIN_TOKEN	Yes, to issue or upgrade keys	Admin secret. Missing or blank fails closed (403).
SAM_API_KEY	Yes, for contract tools	Your SAM.gov key. Never commit a real value.
PUBRECORDS_SEC_USER_AGENT	Production	Identifying User-Agent for SEC EDGAR.
OPENCORPORATES_TOKEN	No	Raises the OpenCorporates anonymous cap.
COURTLISTENER_TOKEN	No	Raises the CourtListener anonymous cap.
PUBRECORDS_CACHE_TTL	No	Cache TTL in seconds (default 86400).
PUBRECORDS_DB_PATH	No	SQLite file for cache and API keys.
PORT	No	Listen port. Railway sets this.

---

Data freshness

Responses are cached for 24 hours by default.

Source	Refresh cadence
OpenCorporates	Daily / weekly (varies by jurisdiction)
SEC EDGAR	Filings appear minutes after submission
USASpending.gov	Monthly, with fiscal-year backfills
CourtListener (RECAP)	Daily, depending on uploads
NPPES NPI	Weekly
FCC License-View	Daily
Grants.gov	Posted opportunities, as the agency updates them
SAM.gov	Contract notices, as contracting offices post them

For fresher queries, set PUBRECORDS_CACHE_TTL=300 (5 minutes). That multiplies upstream traffic.

---

Data gaps and source limits

The server returns a structured error envelope instead of invented rows when a query is outside coverage.

1. UCC filings — there is no uniform federal UCC API. get_ucc_filings returns {"error": "not_implemented"} until per-state adapters land.
2. State professional licenses — healthcare (NPI) and FCC are covered. Bar, real estate, contractor, and CPA licenses are state-by-state.
3. OpenCorporates rate limits — anonymous traffic is capped. Set OPENCORPORATES_TOKEN for production.
4. SEC EDGAR full-text — broad terms return wide sets. Combine with form_type.
5. CourtListener — federal PACER/RECAP. State courts are not guaranteed.
6. SAM.gov — contract tools do nothing until SAM_API_KEY is set in the environment. Apply at https://sam.gov. The key is not embedded in this repo.
7. SAM award history — search_awards reads Award Notice rows from the opportunities API. Deeper recipient rollups stay on lookup_federal_spending (USASpending).
8. Match scores — match_opportunities is deterministic token overlap on title and agency. It does not call a model.
9. No consumer PII — entity-level public records only.

---

License and compliance

This server proxies and caches public records that are already free to access from federal and public sources. Cached payloads are kept for 24 hours and can be flushed by deleting the SQLite file. Customer API keys and the admin token belong in the environment and the SQLite key store. Do not commit them.