usaspending mcp server

Public Hosted Server: https://usaspending.caseyjhand.com/mcp

---

Tools

18 tools covering the full USAspending.gov API surface — award discovery and detail, recipient and agency profiles, spending analytics (by geography, category, and time), disaster/emergency spending, and federal account data:

Tool	Description
usaspending_search_awards	Search federal awards by keyword, recipient, agency, award type, NAICS code, location, or date range. Returns ranked award summaries with recipient names, amounts, agencies, and award IDs for chaining.
usaspending_get_award	Fetch full details of a federal award by its generated ID. Returns contract or assistance data, parent IDV info, subaward count, and funding account linkages.
usaspending_get_idv_awards	List child contracts and task/delivery orders placed under an IDV award. Each row includes a generated_unique_award_id for chaining into usaspending_get_award.
usaspending_get_award_transactions	List individual transactions (modifications, amendments) on an award. Reveals spending history and obligation changes over time.
usaspending_get_award_subawards	List subaward contracts or grants under a prime award. Reveals the sub-contractor or sub-grantee layer — who actually does the work.
usaspending_get_award_federal_accounts	List the Treasury federal accounts that funded an award, with the amount obligated from each. Returns federal_account for chaining into usaspending_get_federal_account.
usaspending_search_recipients	Search for organizations receiving federal funds by name, UEI, or DUNS. Returns recipient hash IDs, UEI/DUNS, total award amounts, and hierarchy level. Paginated — page through with page; page_metadata.total reports the full match count.
usaspending_get_recipient	Fetch a recipient's profile: address, business types, parent organization, alternate names, and total award amounts by type.
usaspending_get_agency	Fetch an agency's fiscal year overview: mission, budget authority, obligation totals, sub-agency count, and DEF codes. Accepts a 3-digit toptier_code or an agency_slug from award search results.
usaspending_spending_by_geography	Aggregate federal spending by state, county, or congressional district. Returns per-capita figures when combined with population data.
usaspending_spending_by_category	Aggregate spending grouped by NAICS code, PSC code, awarding agency, funding agency, CFDA program, or recipient. Returns top items with amounts for trend and breakdown analysis.
usaspending_spending_over_time	Fetch aggregated spending by fiscal year, fiscal quarter, or fiscal month. Filter by award type, agency, recipient, or keyword to trace trends in a specific area.
usaspending_disaster_spending	Fetch disaster and emergency supplemental spending (COVID-19, hurricanes, etc.) broken down by agency, CFDA program, recipient, or geography. Filter by DEF codes to isolate a specific appropriation.
usaspending_get_federal_account	Fetch a federal account's budget data: total obligations, outlays, budgetary resources, and the per-Treasury-Account-Symbol component breakdown. Account codes come from usaspending_search_federal_accounts.
usaspending_get_federal_account_breakdown	Break a federal account's obligations down by program activity (what the money funds) or object class (what it buys). Paginated with a total count.
usaspending_search_federal_accounts	List and keyword-search federal accounts by agency identifier or title keyword. Returns account numbers for chaining into usaspending_get_federal_account.
usaspending_list_agencies	List all top-tier federal agencies with toptier codes, budget authority amounts, and obligation totals. Entry point for agency navigation.
usaspending_autocomplete_filters	Look up valid code values for filter fields: NAICS, PSC, CFDA, recipient names, or agency names. Use before filtering to discover the right code from a description.

usaspending_search_awards

Search for federal awards across contracts, grants, loans, direct payments, and IDVs.

• Full-text keyword search across award descriptions, recipient names, and locations
• Filter by award type codes (A/B/C/D = contracts, 02/03/04/05 = grants, 06/10 = direct payments, 07/08 = loans, IDV_* = IDVs)
• Filter by awarding or funding agency (toptier or subtier), recipient name, NAICS code, and place of performance
• Date range filtering — earliest 2007-10-01 via search API
• Pagination via limit (max 100) and page; page_metadata.has_next signals more results and is true on any full page — the endpoint stops advertising continuation once page × limit reaches 10,000, so page fullness is the honest signal past that point. Page-number paging caps at a 50,000-result offset — beyond it, continue with keyset pagination using the last_record_sort_value + last_record_unique_id cursor, which is only returned below the 10,000-result offset and has to be captured before crossing it
• Returns generated_internal_id for chaining to usaspending_get_award and agency_slug for chaining to usaspending_get_agency

---

usaspending_get_award

Fetch complete details for a single federal award by its generated ID.

• Returns type, description, total obligation, date signed, and subaward count
• Exposes recipient.recipient_hash for chaining to usaspending_get_recipient
• Exposes parent_award.generated_unique_award_id for traversing IDV parent chains
• Includes NAICS code and product/service code from the latest transaction
• Returns account_obligations_by_defc linking the award to specific disaster/emergency appropriations
• Award IDs use the generated_unique_award_id format (e.g., CONT_AWD_FA862118F6251_9700_...)

---

usaspending_get_idv_awards

List child contracts and orders placed under an IDV (Indefinite Delivery Vehicle) award.

• award_id must be the generated_unique_award_id of the parent IDV — from usaspending_search_awards (generated_internal_id field) or from usaspending_get_award
• type selects what to list: child_awards (task/delivery orders), child_idvs (sub-IDVs), or grandchild_awards
• Each row returns generated_unique_award_id for chaining into usaspending_get_award for full detail
• Pagination via limit and page; note: no total count is available from this endpoint
• An invalid award_id or an IDV with no children of the requested type returns an empty result set

---

usaspending_get_award_transactions

List obligation history and modifications for an award.

• Each row is one transaction: action_date, federal_action_obligation, modification_number, and description
• Pagination via limit and page; configurable sort and order. No total count is available from this endpoint

---

usaspending_get_award_subawards

List subawards under a prime contract or grant.

• Each row covers: subaward number, description, action date, amount, and recipient name
• Reveals the supply chain below the prime — who actually performs the work
• Pagination via limit and page; configurable sort and order. No total count is available from this endpoint

---

usaspending_get_award_federal_accounts

List the Treasury federal accounts that funded an award — the award → appropriation link.

• award_id must be a generated_unique_award_id — from usaspending_search_awards (generated_internal_id field) or usaspending_get_award
• Each row returns federal_account (AGENCY-MAIN format, e.g. 080-0120) for chaining into usaspending_get_federal_account, plus the amount obligated from that account and the funding agency behind it
• Distinct from usaspending_get_award account_obligations_by_defc, which breaks funding down by Disaster/Emergency Funding code rather than by account
• Pagination via limit (max 100) and page; count in page_metadata is the total across pages
• An award_id that does not exist returns an empty list rather than an error — the upstream reports no not-found signal for this endpoint

---

usaspending_search_recipients

Search for organizations receiving federal funds by name, UEI, or DUNS.

• Returns recipient IDs (UUID hashes with level suffix: -P parent, -C child, -R root), UEI, DUNS, name, recipient level, and total award amount
• results[].id chains to usaspending_get_recipient; uei and duns chain to SAM.gov or SEC EDGAR
• Paginated via limit (max 100) and page; page_metadata reports total, page, and has_next — page through to reach matches beyond the first page

---

usaspending_get_recipient

Fetch a recipient's full profile.

• Returns address, business type classifications, parent organization, alternate names
• Optionally scope to a specific fiscal year and award type
• Requires the UUID-based recipient ID from usaspending_search_recipients

---

usaspending_get_agency

Fetch an agency's current fiscal year overview.

• Returns mission, budget authority amount, obligation amount, sub-agency count, and DEF codes
• Accepts either a 3-digit toptier_code (e.g., 097 for DoD) or an agency_slug (e.g., department-of-defense) — slugs appear in award search results, eliminating an intermediate lookup
• Includes sub-agency breakdown with transaction counts

---

usaspending_spending_by_geography

Aggregate federal spending by geographic unit.

• scope: place_of_performance or recipient_location
• geo_layer: state, county, or district
• Returns shape_code, display_name, aggregated_amount, and per_capita (when population is available)
• limit accepts 1–500 (default 50). The upstream endpoint is not paginated — a nationwide county query matches over 3,000 areas — so areas are ranked by aggregated_amount descending and capped client-side; total_areas_available reports the full match count
• Omitting filters entirely aggregates every award type (contracts, IDVs, grants, direct payments, loans, insurance, and unspecified); the substitution is disclosed on the response
• Geographic filters require FIPS codes or 2-letter state abbreviations — use a geocoding server (e.g., Census or OpenStreetMap) to resolve place names first

---

usaspending_spending_by_category

Aggregate spending broken down by a single dimension.

• category enum maps to the right sub-route: naics, psc, awarding_agency, funding_agency, cfda, or recipient
• Returns top items with amounts and codes for trend analysis
• Accepts the standard award filter object for scoping to a specific agency, time period, or keyword
• Pagination via limit and page; no total count is available from this endpoint

---

usaspending_spending_over_time

Fetch aggregated spending grouped by time period.

• group: fiscal_year, quarter, or month
• Filter by award type, agency, recipient, or keyword to trace trends in a specific area
• subawards: true shifts aggregation to the subaward layer

---

usaspending_disaster_spending

Fetch disaster and emergency supplemental spending consolidated from nine+ API endpoints.

• dimension enum selects the breakdown axis: overview, agency, cfda, recipient, or geography
• spending_type selects between award-level obligations and outlays (award) and total spending including direct non-award amounts (total, agency and recipient dimensions only)
• Filter by def_codes to isolate a specific emergency appropriation (e.g., COVID-19 = L, M, N, O, P, U)
• Returns obligation, outlay, and award count per row

---

usaspending_get_federal_account

Fetch budget data for a federal account identified by its account code.

• Returns account title, federal account code, agency identifier, parent agency, and bureau
• Includes the fiscal year snapshot: total obligations, gross outlays, and budgetary resources
• children breaks the account into its Treasury Account Symbol (TAS) components, each with its own obligated, outlay, and budgetary-resource amounts — one entry per availability period, bounded and returned in full
• Account codes come from account_number in usaspending_search_federal_accounts results, or federal_account in usaspending_get_award_federal_accounts results
• For obligations broken down by program activity or object class, use usaspending_get_federal_account_breakdown

---

usaspending_get_federal_account_breakdown

Break a federal account's obligations down by program activity or object class.

• dimension enum selects the axis: program_activity (what the money funds) or object_class (what it buys — personnel, supplies, contracts)
• Each row returns the code, name, and obligated amount; program_activity rows also carry type — PAC/PAN (legacy program activity code/name) or PARK (Program Activity Reporting Key), both of which can appear for the same account
• Pagination via limit (max 100) and page; total in page_metadata is the true row count across pages
• An account code that does not exist returns an empty list rather than an error — unlike usaspending_get_federal_account, these routes report no not-found signal

---

usaspending_search_federal_accounts

List and keyword-search federal accounts by agency or title keyword.

• keyword filters by account name/title (e.g., "defense", "transportation")
• agency_identifier filters to a specific agency by 3-digit code (e.g., "097" for DoD) — use usaspending_list_agencies to look up codes
• sort_field enum: account_name, account_number, budgetary_resources (default), managing_agency
• Returns account_number (format "097-8097") for chaining into usaspending_get_federal_account for full budget detail
• Pagination via limit and page; count in page_metadata is the total matches

---

usaspending_list_agencies

List all top-tier federal agencies.

• Returns agency name, abbreviation, toptier_code, agency_slug, obligated amount, and budget authority amount for the current fiscal year
• Entry point for agency navigation — toptier_code is required by usaspending_get_agency and agency filters
• Configurable sort and order

---

usaspending_autocomplete_filters

Discover valid code values for award filter fields.

• type enum selects the lookup: naics, psc, cfda, awarding_agency, or recipient
• Returns matching codes and names — use before filtering to find the right code when you only know a description (e.g., "software" → NAICS codes); recipient matches also carry uei/duns
• The naics lookup matches official NAICS title text, not colloquial industry language — "software" and "aircraft" resolve, "cybersecurity" and "aircraft maintenance" return nothing. Fall back to the broader industry term the NAICS title would use
• Consolidates five autocomplete endpoints into one tool
• limit accepts 1–500 and is enforced client-side — the recipient lookup unions three upstream match buckets (name, UEI, DUNS) and can return up to 3x the requested count, so its results are capped before returning; the other four honor limit exactly

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

USAspending-specific:

• Full USAspending.gov API v2 coverage — award search, award detail, recipient and agency profiles, spending analytics, disaster spending, and federal accounts
• No authentication required — all data is public domain under the DATA Act
• usaspending_spending_by_category consolidates 14 category sub-routes behind a single category enum; usaspending_disaster_spending consolidates 9+ disaster endpoints behind dimension + spending_type enums
• usaspending_get_agency accepts both toptier_code and agency_slug, eliminating the intermediate agency-list lookup that award search results would otherwise require
• usaspending_autocomplete_filters serves as the code-discovery step before filtering — maps human-readable terms to NAICS, PSC, CFDA, and agency codes

Agent-friendly output:

• Chaining fields on every response — generated_internal_id, agency_slug, recipient_hash, and account_code fields are surfaced explicitly so agents can follow the money without parsing identifiers out of display strings
• Pagination metadata on list responses — page_metadata.has_next and page_metadata.page let agents iterate large result sets without guessing. page_metadata.total is carried wherever the upstream endpoint publishes one; usaspending_get_award_transactions, usaspending_get_award_subawards, and usaspending_spending_by_category sit on endpoints that publish none, so has_next is the only continuation signal there
• Structured geographic outputs — shape_code, display_name, aggregated_amount, and per_capita are typed consistently across state, county, and district views for composable analysis

Getting started

Public Hosted Instance

A public instance is available at https://usaspending.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "usaspending-mcp-server": {
      "type": "streamable-http",
      "url": "https://usaspending.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file. No API key is required — USAspending.gov data is public domain.

{
  "mcpServers": {
    "usaspending-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/usaspending-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "usaspending-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/usaspending-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "usaspending-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/usaspending-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.0 or higher (or Node.js v24+).
• No API key required — USAspending.gov is a public data platform with no authentication requirement.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/usaspending-mcp-server.git

1. Navigate into the directory:

cd usaspending-mcp-server

1. Install dependencies:

bun install

1. Configure environment (optional):

cp .env.example .env
# edit .env if you need to override defaults

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. No environment variables are required — the defaults work out of the box.

Variable	Description	Default
USASPENDING_BASE_URL	Base URL for the USAspending.gov API.	https://api.usaspending.gov/api/v2/
USASPENDING_TIMEOUT_MS	HTTP timeout in milliseconds, applied per attempt.	30000
USASPENDING_RETRY_BUDGET_MS	Wall-clock budget covering every retry attempt of one request, so a slow endpoint cannot re-pay the per-attempt timeout on each retry. Accepts 1000–300000.	1.5 × USASPENDING_TIMEOUT_MS
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_PORT	Port for the HTTP server.	3010
MCP_HTTP_ENDPOINT_PATH	HTTP endpoint path.	/mcp
MCP_SESSION_MODE	Session mode: auto, stateful, or stateless; auto resolves to stateful. Shipped as stateless in both .env.example and the Dockerfile — this server holds no per-session state.	auto
MCP_PUBLIC_URL	Public origin override for TLS-terminating reverse-proxy deployments.	—
MCP_AUTH_MODE	Auth mode: none, jwt, or oauth.	none
MCP_LOG_LEVEL	Log level (debug, info, warning, error, etc.).	info
LOGS_DIR	Directory for log files (Node.js only).	<project-root>/logs
STORAGE_PROVIDER_TYPE	Storage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1.	in-memory
OTEL_ENABLED	Enable OpenTelemetry instrumentation.	false

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t usaspending-mcp-server .
docker run --rm -p 3010:3010 usaspending-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/usaspending-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory	Purpose
src/index.ts	createApp() entry point — registers tools and inits services.
src/config	Server-specific environment variable parsing and validation with Zod.
src/mcp-server/tools	Tool definitions (*.tool.ts).
src/services	USAspending API client and service layer.
tests/	Unit and integration tests mirroring src/.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools via the barrels in src/mcp-server/tools/definitions/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.