# io.github.cyanheads/usaspending-mcp-server (remote · usaspending.caseyjhand.com)

Access US federal award, recipient, agency, and spending analytics data from USAspending.gov.

- Trust score: 67/100 (medium)
- Change this week: +4
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- remote · `usaspending.caseyjhand.com`: 67/100 (this document), [markdown](https://verifymcp.io/servers/cyanheads-usaspending-mcp-server/usaspending.md), [page](https://verifymcp.io/servers/cyanheads-usaspending-mcp-server/usaspending)
- npm · `@cyanheads/usaspending-mcp-server`: 35/100, [markdown](https://verifymcp.io/servers/cyanheads-usaspending-mcp-server/cyanheads-usaspending-mcp-server.md), [page](https://verifymcp.io/servers/cyanheads-usaspending-mcp-server/cyanheads-usaspending-mcp-server)

## Channel facts

- Endpoint: `https://usaspending.caseyjhand.com/mcp`
- Transports: `streamable-http`
- Auth: `none`
- Version: `0.4.1`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically against the live server, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Endpoint Security**: 66/100
  - The endpoint's TLS certificate is valid, in date, and uses a strong key.
  - Authorisation not fully verified: no authorisation is required to call this server, and 18 tool(s) never declared a destructiveHint. The MCP spec treats an absent hint as destructive by default, so we cannot call this surface safe.
  - HTTPS is enforced; there's no plaintext access path.
  - The HSTS (Strict-Transport-Security) header is present.
  - DNSSEC is configured correctly; the domain's records validate against the full chain to the root.
- **Transport & Reachability**: 100/100
  - Verified streamable-http transport via a live MCP handshake.
- **Schema Quality & AI Usability**: 64/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 4559 tokens (~253/item across 18 items; 18 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 21/100
  - Stability check failed: schema churn in the 8 days we've observed: 1 tool removals, 0 breaking changes, 0 auth/transport breaks, 1 additions.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add --transport http cyanheads-usaspending-mcp-server https://usaspending.caseyjhand.com/mcp
```

### Codex

```toml
[mcp_servers.cyanheads-usaspending-mcp-server]
url = "https://usaspending.caseyjhand.com/mcp"
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cyanheads-usaspending-mcp-server": {
      "type": "remote",
      "url": "https://usaspending.caseyjhand.com/mcp",
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add cyanheads-usaspending-mcp-server --url https://usaspending.caseyjhand.com/mcp --transport streamable-http
```

### Hermes

```yaml
mcp_servers:
  cyanheads-usaspending-mcp-server:
    url: "https://usaspending.caseyjhand.com/mcp"
```

### Other

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

The mcpServers block is a cross-client convention. Remote transports vary, so check your client's docs.

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-02 (score 67, +1)

No change was recorded against any check on this day. Stability & Change Management went from 14 to 18.

### 2026-07-31 (score 66, +2)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 64, +1)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-27 (score 63, +1)

- [security regression] Stability: unverified → fail
- [security regression] Tool “usaspending_autocomplete” was removed
- [security] The server rewrote its instructions, which are the text every model session reads
- [security] Tool “usaspending_spending_by_category” rewrote its description, which is the text the model reads
- [security] Tool “usaspending_spending_over_time” rewrote its description, which is the text the model reads
- [functional improvement] Stability: unverified → 0.03
- [functional] Schema quality: excellent → good
- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server
- [functional] Server version: 0.4.0 → 0.4.1
- [functional] Server version: 0.3.2 → 0.4.0
- [functional] Server version: 0.3.0 → 0.3.2
- [functional] New tool “usaspending_autocomplete_filters”
- [cosmetic] “usaspending_spending_by_geography” added an optional parameter “limit”
- [cosmetic] “usaspending_search_awards” reworded the description of “naics_codes”
- [cosmetic] “usaspending_search_awards” reworded the description of “agency_name”
- [cosmetic] “usaspending_search_awards” reworded the description of “last_record_sort_value”
- [cosmetic] “usaspending_search_awards” reworded the description of “page”

### 2026-07-26 (score 62)

First indexed and scored.

## MCP tools (18)

### `usaspending_list_agencies` (~119 tokens)

List Federal Agencies

List all top-tier federal agencies with toptier codes, agency slugs, budget authority amounts, and obligation totals for the current fiscal year. Use this as the entry point for agency navigation — toptier codes and agency slugs are required inputs for usaspending_get_agency and agency-based filters on spending analysis tools.

Input parameters:

- `order` (string): Sort direction: asc or desc
- `sort` (string): Sort field: agency_name (alphabetical), budget_authority_amount, obligated_amount, or outlay_amount

Output parameters:

- `agency_count` (number): Total number of top-tier federal agencies returned
- `results` (array): List of top-tier federal agencies with budget and obligation data
- `total` (number): Total number of agencies returned

### `usaspending_autocomplete_filters` (~303 tokens)

Autocomplete Codes and Names

Look up valid code values for filter fields by searching free-text descriptions. Use the type parameter to select the lookup table: naics (NAICS industry codes), psc (product/service codes), cfda (CFDA/Assistance Listing program numbers), awarding_agency (agency names and IDs), or recipient (recipient names with UEI/DUNS). Call this before filtering awards when you know a description but not the exact code. Returns matching codes and names for use in other tool filters.

Input parameters:

- `limit` (integer): Maximum number of results to return (1–500), enforced client-side. The recipient lookup unions three upstream match buckets (name, UEI, DUNS) and can return up to 3x this value, so its results are ca…
- `search_text` (string, required): Free-text search string — use a description, keyword, or partial code to find matches
- `type` (string, required): Lookup table to search: naics (industry codes), psc (product/service codes), cfda (assistance programs), awarding_agency (agency names), recipient (recipient names)

Output parameters:

- `cap` (number): The limit that was applied.
- `lookup_type` (string): Lookup table that was searched
- `query` (string): Search text sent to the autocomplete API
- `result_count` (number): Number of matching results returned
- `results` (array): Matching codes and names
- `search_text` (string): Search text used
- `shown` (number): Number of results returned.
- `total` (number): Number of results returned
- `truncated` (boolean): True when results were capped at the limit.
- `type` (string): Lookup table searched

### `usaspending_search_awards` (~740 tokens)

Search Federal Awards

Search federal awards by keyword, recipient, agency, award type, NAICS code, location, or date range. Returns ranked award summaries including recipient names, amounts, awarding agencies, and generated award IDs for use with usaspending_get_award. Award types: A/B/C/D = contracts, 02/03/04/05 = grants, 06/10 = direct payments, 07/08 = loans, IDV_A/IDV_B/IDV_C/IDV_D/IDV_E = IDVs. Dates must be ISO 8601 (YYYY-MM-DD). Earliest data: 2007-10-01 via search API. DoD contracts have a 90-day publication lag.

Input parameters:

- `agency_name` (string): Filter to a specific awarding agency by name (e.g., "Department of Defense"). Use usaspending_autocomplete_filters type=awarding_agency to find exact names.
- `award_type_codes` (array): Filter by award type codes. All codes must belong to a single group: A/B/C/D (contracts), 02/03/04/05 (grants), 06/10 (direct payments), 07/08 (loans), IDV_A–IDV_E (IDVs). Defaults to contracts. Mixi…
- `filters` (object): Optional analytics-style filter object mirroring the shape the spending analytics tools accept, for reusing one filter set across tools. When both this object and the equivalent top-level flat filter…
- `keyword` (string): Full-text search across award descriptions, recipient names, and place names
- `last_record_sort_value` (string): Keyset-pagination cursor: the last_record_sort_value from a prior response page_metadata. Provide together with last_record_unique_id to fetch the next page past the 50,000-result page-number cap. Th…
- `last_record_unique_id` (integer): Keyset-pagination cursor: the last_record_unique_id from a prior response page_metadata. Provide together with last_record_sort_value.
- `limit` (integer): Maximum results per page (1–100)
- `location_filter` (object): Filter by place of performance location. Uses FIPS codes and 2-letter state abbreviations, not place names — use a geocoding server to resolve names to codes first.
- `naics_codes` (array): Filter by NAICS industry codes (e.g., ["541512"]). Use usaspending_autocomplete_filters type=naics to look up codes.
- `order` (string): Sort direction
- `page` (integer): Page number (1-based). Page-number pagination caps at a 50,000-result offset (page × limit), but the keyset cursor below is only returned while the offset stays under 10,000 — capture the cursor pair…
- `recipient_name` (string): Filter by recipient name (partial match); maps to this endpoint's recipient_search_text. This endpoint has no recipient_id filter — use usaspending_search_recipients to look up a recipient by name.
- `sort` (string): Sort field for results
- `time_period` (object): Filter awards by date range (action date)

Output parameters:

- `applied_agency_name` (string): Awarding agency name filter applied
- `applied_keyword` (string): Keyword filter applied to this search
- `applied_naics_codes` (string): NAICS codes filter applied (comma-separated)
- `applied_time_period_end` (string): End date filter applied (YYYY-MM-DD)
- `applied_time_period_start` (string): Start date filter applied (YYYY-MM-DD)
- `cap` (number): Per-page cap (limit) applied to this page.
- `has_next` (boolean): Whether more results may remain — set on a full page even when the upstream flag reports none.
- `notice` (string): Recovery hint when results are empty — echoes applied filters and suggests how to broaden. Absent when results are present.
- `page` (number): Current page number returned
- `page_metadata` (object): Pagination metadata. This endpoint does not return a total match count; use has_next and the cursor pair to page.
- `results` (array): Matching award summaries
- `shown` (number): Number of awards returned on this page.
- `truncated` (boolean): True when this page was capped at `limit` and more results may remain (continue via page or the cursor).
- `upstream_messages` (array): Notices the USAspending API returned with this response — e.g. a supplied filter it ignored because this endpoint does not support it. Every successful response also carries a standing advisory that…

### `usaspending_get_award` (~197 tokens)

Get Award Details

Fetch full details of a federal award by its generated unique award ID. Returns contract or assistance award data including recipient info, agency hierarchy, period of performance, place of performance, funding account linkages (account_obligations_by_defc), parent IDV information, and subaward count. Use generated_internal_id values from usaspending_search_awards as input. Recipient hashes can be passed to usaspending_get_recipient; NAICS codes can be used in usaspending_search_awards filters. For IDV-category awards (category="idv"), use usaspending_get_idv_awards to list the child contracts and task/delivery orders placed under them.

Input parameters:

- `award_id` (string, required): Generated unique award ID (e.g., CONT_AWD_FA862118F6251_9700_FA862115D6276_9700) — use generated_internal_id from usaspending_search_awards

Output parameters:

- `account_obligations_by_defc` (array): Funding breakdown by Disaster/Emergency Funding (DEF) code — links to disaster appropriations
- `awarding_agency` (object): Awarding agency hierarchy
- `base_and_all_options_value` (number): Base and all options value in USD (contracts)
- `category` (string): Award category (contract, grant, direct_payment, loan, idv, other)
- `cfda` (object): CFDA program (grants/assistance)
- `date_signed` (string): Date award was signed (YYYY-MM-DD)
- `description` (string): Award description
- `fain` (string): Federal Award Identification Number (for assistance)
- `funding_agency` (object): Funding agency hierarchy
- `generated_unique_award_id` (string): Generated unique award ID
- `naics` (object): NAICS code (contracts)
- `parent_award` (object): Parent IDV information (contracts only)
- `period_of_performance` (object): Period of performance dates
- `piid` (string): Procurement Instrument Identifier (for contracts)
- `place_of_performance` (object): Place of performance
- `product_or_service_code` (object): Product or service code (contracts)
- `recipient` (object): Recipient details
- `subaward_count` (number): Number of subawards; use with usaspending_get_award_subawards
- `total_obligation` (number): Total obligation amount in USD
- `total_outlays` (number): Total outlay amount in USD
- `type` (string): Award type code
- `type_description` (string): Human-readable award type

### `usaspending_get_award_transactions` (~150 tokens)

Get Award Transactions

List individual transactions (contract modifications, grant amendments) on a federal award. Each transaction represents a change event — obligation modifications, performance period extensions, scope changes, etc. Use this to trace the spending history and obligation changes over the life of an award. Award IDs come from usaspending_search_awards (generated_internal_id field).

Input parameters:

- `award_id` (string, required): Generated unique award ID (generated_internal_id from usaspending_search_awards)
- `limit` (integer): Maximum transactions per page (1–100)
- `order` (string): Sort direction
- `page` (integer): Page number (1-based)
- `sort` (string): Sort field for transactions

Output parameters:

- `award_id` (string): Award ID queried
- `current_page` (number): Current page returned
- `has_next_page` (boolean): Whether there are more pages of transactions
- `notice` (string): Guidance when no transactions were returned — helps confirm the award_id is a valid generated_internal_id. Absent when results are present.
- `page_metadata` (object): Pagination metadata
- `queried_award_id` (string): Award ID whose transactions were listed
- `results` (array): List of transactions for this award
- `totalCount` (number): Total transaction count across all pages (when available)

### `usaspending_get_award_subawards` (~162 tokens)

Get Award Subawards

List subaward contracts or grants under a prime federal award. Reveals the sub-contractor or sub-grantee layer — the organizations that actually perform the work. Each row shows the subaward number, amount, description, action date, and recipient. Check subaward_count on usaspending_get_award first to confirm subawards exist before calling this tool.

Input parameters:

- `award_id` (string, required): Generated unique award ID (generated_internal_id from usaspending_search_awards)
- `limit` (integer): Maximum subawards per page (1–100)
- `order` (string): Sort direction
- `page` (integer): Page number (1-based)
- `sort` (string): Sort field for subawards

Output parameters:

- `award_id` (string): Prime award ID queried
- `current_page` (number): Current page returned
- `has_next_page` (boolean): Whether there are more pages of subawards
- `notice` (string): Guidance when no subawards were returned — suggests checking subaward_count from usaspending_get_award first. Absent when results are present.
- `page_metadata` (object): Pagination metadata
- `prime_award_id` (string): Prime award ID whose subawards were listed
- `results` (array): List of subawards under this prime award
- `totalCount` (number): Total subaward count across all pages (when available)

### `usaspending_get_award_federal_accounts` (~258 tokens)

Get Award Federal Accounts

List the Treasury federal accounts that funded an award, with the amount obligated from each and the funding agency behind it. This is the award → appropriation link: each row returns federal_account (AGENCY-MAIN format, e.g. 080-0120) to chain into usaspending_get_federal_account for the account budget detail. The award_id must be a generated_unique_award_id — from usaspending_search_awards (generated_internal_id field) or usaspending_get_award. Distinct from usaspending_get_award account_obligations_by_defc, which breaks funding down by Disaster/Emergency Funding code rather than by account. An award_id that does not exist returns an empty list rather than an error.

Input parameters:

- `award_id` (string, required): Award generated_unique_award_id (e.g., CONT_AWD_GSFC0198106DNAS526555_8000_-NONE-_-NONE-) — use generated_internal_id from usaspending_search_awards or generated_unique_award_id from usaspending_get_…
- `limit` (integer): Maximum results per page (1–100)
- `page` (integer): Page number (1-based)

Output parameters:

- `award_id` (string): Award ID queried
- `current_page` (number): Current page returned
- `has_next_page` (boolean): Whether there are more pages of funding accounts
- `notice` (string): Recovery hint when results are empty — the award_id may not exist or may have no account linkage. Absent when results are present.
- `page_metadata` (object): Pagination metadata
- `results` (array): Federal accounts funding this award
- `totalCount` (number): Total number of funding accounts across all pages (when available)

### `usaspending_get_idv_awards` (~279 tokens)

Get IDV Child Awards

List child contracts and task/delivery orders placed under an IDV (Indefinite Delivery Vehicle) award. Each row includes the generated_unique_award_id to chain into usaspending_get_award for full detail. The award_id must be the generated_unique_award_id of the parent IDV — obtainable from usaspending_search_awards (generated_internal_id field) or from usaspending_get_award. IDV category awards returned by usaspending_get_award have child orders accessible via this tool.

Input parameters:

- `award_id` (string, required): Parent IDV generated_unique_award_id (e.g., CONT_IDV_NNK14MA74C_8000) — use generated_internal_id from usaspending_search_awards or generated_unique_award_id from usaspending_get_award
- `limit` (integer): Maximum results per page (1–100)
- `order` (string): Sort direction
- `page` (integer): Page number (1-based)
- `sort` (string): Field to sort child awards by (e.g., obligated_amount, period_of_performance_start_date)
- `type` (string): Type of child awards to list: child_awards = task/delivery orders, child_idvs = sub-IDVs, grandchild_awards = orders under sub-IDVs

Output parameters:

- `award_id` (string): Parent IDV award ID queried
- `cap` (number): The per-page limit that was applied.
- `current_page` (number): Current page returned
- `has_next_page` (boolean): Whether more pages of child awards may remain — set on a full page even when the upstream flag reports none.
- `notice` (string): Recovery hint when results are empty — the award may have no children of the requested type. Absent when results are present.
- `page_metadata` (object): Pagination metadata (no total count available from this endpoint)
- `parent_award_id` (string): Parent IDV award ID whose children were listed
- `results` (array): Child awards placed under this IDV
- `shown` (number): Number of child awards returned on this page.
- `truncated` (boolean): True when this page was full and more child awards may remain beyond it.

### `usaspending_search_recipients` (~201 tokens)

Search Award Recipients

Search for organizations or individuals receiving federal funds by name, UEI (Unique Entity Identifier), or DUNS. Returns recipient hash IDs, UEI/DUNS identifiers, total award amounts, and hierarchy level. Results are paginated — use page to retrieve matches beyond the first page; page_metadata.total reports the full match count. Recipient hash IDs from this tool can be passed to usaspending_get_recipient for full profiles. Recipient level: P = parent organization, C = child entity, R = standalone.

Input parameters:

- `award_type` (string): Filter by award type category to scope the total amounts returned
- `keyword` (string, required): Name, UEI, DUNS, or keyword to search for — partial matches are supported
- `limit` (integer): Maximum results per page (1–100)
- `page` (integer): Page number (1-based) — request the next page to retrieve matches beyond the first

Output parameters:

- `has_next` (boolean): Whether there are more pages of results
- `notice` (string): Recovery hint — how to continue to the next page when more results exist, or how to broaden the search when empty. Absent when the full match set fits on this page.
- `page` (number): Current page number returned
- `page_metadata` (object): Pagination metadata — page through with the page input to reach later matches
- `recipient_count` (number): Number of matching recipients returned on this page
- `results` (array): Matching recipients
- `totalCount` (number): Total matching recipients across all pages

### `usaspending_get_recipient` (~210 tokens)

Get Recipient Profile

Fetch a recipient's full profile including address, business type codes, parent organization, alternate names, and total transaction and loan amounts. Recipient IDs are UUID hashes with a level suffix (-P parent, -C child, -R standalone) from usaspending_search_recipients or usaspending_get_award. Optionally scope the totals to a specific fiscal year and award type. UEI and DUNS values can be used to cross-reference with SAM.gov and SEC EDGAR.

Input parameters:

- `award_type` (string): Award type category to scope award totals
- `fiscal_year` (integer): Fiscal year to scope award totals (e.g., 2024)
- `recipient_id` (string, required): Recipient hash ID (UUID with level suffix, e.g., b97d19b0-833c-8d8f-3a2c-157d04ea55ef-P) — from usaspending_search_recipients or usaspending_get_award

Output parameters:

- `alternate_names` (array): Alternate business names
- `business_types` (array): Business type codes
- `duns` (string): DUNS number (legacy)
- `location` (object): Recipient address
- `name` (string): Recipient legal business name
- `parent_name` (string): Parent organization name
- `parent_uei` (string): Parent organization UEI
- `recipient_id` (string): Recipient hash ID
- `recipient_level` (string): Hierarchy level: P = parent, C = child, R = standalone
- `total_face_value_loan_amount` (number): Total face value of loans in USD
- `total_face_value_loan_transactions` (number): Number of face-value loan transactions
- `total_transaction_amount` (number): Total transaction (award) amount in USD; scoped by fiscal_year/award_type when provided
- `total_transactions` (number): Total number of award transactions
- `uei` (string): Unique Entity Identifier (SAM.gov)

### `usaspending_get_agency` (~252 tokens)

Get Agency Overview

Fetch an agency's fiscal-year overview including mission, budgetary resources, obligation and outlay totals (for the most recent fiscal year), sub-agency count, and DEF codes for disaster/emergency funding. Also returns a paginated sub-agency breakdown with obligation and transaction counts. Accepts either a 3-digit toptier_code (e.g., 097 for DoD, 012 for Agriculture) or an agency_slug (e.g., department-of-defense) — both appear in usaspending_list_agencies results and award search results.

Input parameters:

- `agency_slug` (string): URL-friendly agency slug (e.g., department-of-defense) — from usaspending_list_agencies or award search results. Use either toptier_code or agency_slug, not both.
- `page` (integer): Sub-agency breakdown page (1-based, 10 per page). Use with sub_agency_page_metadata.has_next to page through the full list.
- `toptier_code` (string): 3-digit toptier agency code (e.g., 097, 012) — from usaspending_list_agencies. Use either toptier_code or agency_slug, not both.

Output parameters:

- `abbreviation` (string): Agency abbreviation
- `agency_id` (number): Internal agency ID
- `budgetary_resources_amount` (number): Total budgetary resources in USD for the fiscal year
- `def_codes` (array): Disaster/Emergency Funding (DEF) codes applicable to this agency
- `fiscal_year` (number): Fiscal year the budgetary totals below reflect (most recent available)
- `has_more_sub_agencies` (boolean): Whether more sub-agency pages are available
- `mission` (string): Agency mission statement
- `name` (string): Agency full name
- `notice` (string): Guidance when the sub-agency breakdown is truncated — how to page for the rest. Absent when the last page is shown.
- `obligated_amount` (number): Total amount obligated in USD for the fiscal year
- `outlay_amount` (number): Total outlays in USD for the fiscal year
- `sub_agencies` (array): Sub-agency breakdown within this toptier agency (one page)
- `sub_agency_page` (number): Current sub-agency page returned
- `sub_agency_page_metadata` (object): Pagination metadata for the sub-agency breakdown
- `sub_agency_total` (number): Total sub-agencies across all pages (when available)
- `subtier_agency_count` (number): Number of sub-agencies within this toptier agency
- `toptier_code` (string): 3-digit toptier agency code
- `website` (string): Agency website URL

### `usaspending_spending_by_geography` (~249 tokens)

Spending by Geography

Aggregate federal spending by state, county, or congressional district. Useful for per-capita analysis, regional comparisons, and mapping federal investment patterns. Geographic filters accept FIPS codes and 2-letter state abbreviations — NOT place names. Resolve place names to FIPS codes using a geocoding server (Census or OpenStreetMap) before applying location filters. Chain per-capita results with Census population data for meaningful comparisons.

Input parameters:

- `filters` (object): Optional filters to scope the spending aggregation
- `geo_layer` (string, required): Geographic granularity: state (50 states), county (county-level), or district (congressional district)
- `limit` (integer): Maximum geographic areas to return, ranked by aggregated_amount descending (1–500). The upstream endpoint is not paginated — it returns every matching area in one response — so this caps client-side.…
- `scope` (string, required): Which location to aggregate by: place_of_performance (where work is done) or recipient_location (where the recipient is based)
- `subawards` (boolean): Include subaward data instead of prime award data

Output parameters:

- `applied_agency_name` (string): Awarding agency name filter applied
- `applied_award_type_default` (string): Disclosure that no filters were supplied, so award_type_codes defaulted to the complete set. Absent when the caller supplied at least one filter.
- `applied_geo_layer` (string): Geographic granularity applied: state, county, or district
- `applied_keywords` (string): Keyword filters applied (comma-separated)
- `applied_naics_codes` (string): NAICS code filters applied (comma-separated)
- `applied_scope` (string): Location scope applied: place_of_performance or recipient_location
- `applied_time_period_end` (string): End date filter applied (YYYY-MM-DD)
- `applied_time_period_start` (string): Start date filter applied (YYYY-MM-DD)
- `area_count` (number): Number of geographic areas returned
- `cap` (number): The limit that was applied.
- `geo_layer` (string): Geographic granularity used
- `notice` (string): Recovery hint when results are empty — suggests how to broaden filters. Absent when results are present.
- `results` (array): Spending totals by geographic area
- `scope` (string): Location scope used for aggregation
- `shown` (number): Number of geographic areas returned.
- `total` (number): Number of geographic areas returned
- `total_areas_available` (number): Number of geographic areas the filters matched, before limit was applied
- `truncated` (boolean): True when the area list was capped at limit.
- `truncationCeiling` (number): Obligation amount of the lowest-ranked area shown — an upper bound on omitted ones.

### `usaspending_spending_by_category` (~176 tokens)

Spending by Category

Aggregate federal spending grouped by a specific dimension: NAICS industry code, PSC product/service code, awarding agency, funding agency, CFDA assistance program, or recipient. Returns top items with obligation amounts — useful for trend and breakdown analysis. Chain NAICS codes into usaspending_search_awards filters or usaspending_autocomplete_filters lookups.

Input parameters:

- `category` (string, required): Breakdown dimension: naics (industry), psc (product/service code), awarding_agency, awarding_subagency, funding_agency, funding_subagency, cfda (assistance programs), recipient_duns, or recipient_par…
- `filters` (object): Optional filters to scope the aggregation
- `limit` (integer): Maximum items to return (1–100)
- `page` (integer): Page number (1-based)

Output parameters:

- `applied_agency_name` (string): Awarding agency name filter applied
- `applied_keywords` (string): Keyword filters applied (comma-separated)
- `applied_naics_codes` (string): NAICS code filters applied (comma-separated)
- `applied_time_period_end` (string): End date filter applied (YYYY-MM-DD)
- `applied_time_period_start` (string): Start date filter applied (YYYY-MM-DD)
- `category` (string): Breakdown dimension used
- `has_next` (boolean): Whether there are more pages
- `notice` (string): Recovery hint when results are empty — suggests how to broaden filters. Absent when results are present.
- `page` (number): Current page returned
- `page_metadata` (object): Pagination metadata
- `results` (array): Top items in this category by obligation amount
- `totalCount` (number): Total number of items in this category (when available)

### `usaspending_spending_over_time` (~192 tokens)

Spending Over Time

Fetch aggregated federal obligation amounts grouped by fiscal year, fiscal quarter, or fiscal month. All grouping is relative to the US government fiscal year (Oct–Sep), so fiscal month 1 is October, not January. Filter by award type, agency, recipient, keyword, or NAICS code to trace spending trends in a specific area. Returns per-period totals and optional breakdowns by award category (contracts, grants, direct payments, IDVs, loans, other).

Input parameters:

- `filters` (object): Filters to scope the time-series aggregation. Defaults to contract awards when omitted.
- `group` (string, required): Time grouping: fiscal_year (annual US govt FY: Oct–Sep), quarter (fiscal quarter), or month (fiscal month — an ordinal within the fiscal year, where 1 = October)
- `subawards` (boolean): Aggregate subaward data instead of prime award data

Output parameters:

- `applied_agency_name` (string): Awarding agency name filter applied
- `applied_keywords` (string): Keyword filters applied (comma-separated)
- `applied_naics_codes` (string): NAICS code filters applied (comma-separated)
- `applied_time_period_end` (string): End date filter applied (YYYY-MM-DD)
- `applied_time_period_start` (string): Start date filter applied (YYYY-MM-DD)
- `group` (string): Time grouping used
- `notice` (string): Recovery hint when no periods are returned — suggests broadening filters. Absent when results are present.
- `period_count` (number): Number of time periods returned
- `results` (array): Time-series of obligation totals
- `time_group` (string): Time grouping applied: fiscal_year, quarter, or month
- `total_periods` (number): Number of time periods returned

### `usaspending_disaster_spending` (~302 tokens)

Disaster and Emergency Spending

Fetch disaster and emergency supplemental spending (COVID-19, hurricanes, infrastructure law, etc.) broken down by agency, CFDA assistance program, recipient, or geography. Use the dimension parameter to select the breakdown axis: overview (top-level totals), agency, cfda, recipient, or geography. Filter by DEF codes (Disaster/Emergency Funding codes) to isolate a specific emergency appropriation. DEF codes appear in usaspending_get_award account_obligations_by_defc and usaspending_get_agency def_codes fields.

Input parameters:

- `dimension` (string, required): Breakdown axis: overview (top-level totals and DEF code funding), agency (by awarding agency), cfda (by assistance program), recipient (by recipient), geography (by state/county)
- `filters` (object): Filters — def_codes is required for all non-overview dimensions (agency, cfda, recipient, geography)
- `limit` (integer): Maximum results per page (1–100). Applies to the agency, cfda, and recipient dimensions; ignored for overview and geography, which are not paginated.
- `page` (integer): Page number (1-based)
- `spending_type` (string): Data type for the agency and recipient dimensions: award (award-level obligations and outlays) or total (includes direct non-award spending). Ignored for cfda and overview; the geography dimension is…

Output parameters:

- `applied_dimension` (string): Breakdown dimension applied
- `cap` (number): The result-set ceiling the upstream applied.
- `current_page` (number): Current page (non-overview dimensions)
- `dimension` (string): Breakdown dimension returned
- `has_next_page` (boolean): Whether there are more pages
- `notice` (string): Caveat explaining a capped total and how to bring the set under the cap.
- `overview` (object): Top-level overview totals (dimension=overview only)
- `page_metadata` (object): Pagination metadata (non-overview dimensions)
- `results` (array): Breakdown results (empty for overview dimension)
- `shown` (number): Number of results returned on this page.
- `spending_type` (string): Data type returned — award/total for agency, cfda, and recipient; obligation for geography; spending for overview
- `totalCount` (number): Total items for paginated dimensions (when available)
- `truncated` (boolean): True when the upstream capped the reachable result set rather than counting it.

### `usaspending_get_federal_account` (~196 tokens)

Get Federal Account

Fetch a federal account's budget data: total obligations, gross outlays, and budgetary resources, plus the per-Treasury-Account-Symbol (TAS) component breakdown in children. Federal accounts connect appropriations law to actual agency spending. Account codes come from usaspending_search_federal_accounts (its account_number output field) or usaspending_get_award_federal_accounts (its federal_account field), and are formatted as AGENCY-MAIN (e.g., 097-0100 for DoD Operation and Maintenance). For obligations broken down by program activity or object class, use usaspending_get_federal_account_breakdown.

Input parameters:

- `account_code` (string, required): Federal account code in AGENCY-MAIN format (e.g., 097-0100). Returned as account_number by usaspending_search_federal_accounts and as federal_account by usaspending_get_award_federal_accounts.

Output parameters:

- `account_title` (string): Full account title
- `agency_identifier` (string): Agency identifier code
- `bureau_name` (string): Bureau name within the agency
- `children` (array): Treasury Account Symbol (TAS) components that make up this federal account, each with its own obligated, outlay, and budgetary-resource amounts. Omitted when the upstream returns none.
- `federal_account_code` (string): Federal account code
- `fiscal_year` (number): Fiscal year of the financial data
- `main_account_code` (string): Main account code
- `parent_agency_name` (string): Managing parent agency name
- `total_budgetary_resources` (number): Total budgetary resources in USD
- `total_gross_outlay_amount` (number): Total gross outlay amount in USD
- `total_obligated_amount` (number): Total obligated amount in USD

### `usaspending_get_federal_account_breakdown` (~249 tokens)

Get Federal Account Breakdown

Fetch a federal account's obligations broken down by program activity (what the money funds) or object class (what it buys — personnel, supplies, contracts). Use the dimension parameter to select the axis. Account codes are AGENCY-MAIN format and come from usaspending_search_federal_accounts (its account_number output field), usaspending_get_award_federal_accounts (its federal_account field), or usaspending_get_federal_account. Paginated with an honest total count. For the account's own metadata and top-level totals, use usaspending_get_federal_account.

Input parameters:

- `account_code` (string, required): Federal account code in AGENCY-MAIN format (e.g., 097-0100). Returned as account_number by usaspending_search_federal_accounts and as federal_account by usaspending_get_award_federal_accounts.
- `dimension` (string, required): Breakdown axis: program_activity (obligations by the program the funds support) or object_class (obligations by the category of goods/services purchased)
- `limit` (integer): Maximum results per page (1–100)
- `page` (integer): Page number (1-based)

Output parameters:

- `account_code` (string): Federal account code queried
- `applied_dimension` (string): Breakdown dimension applied
- `current_page` (number): Current page returned
- `dimension` (string): Breakdown dimension returned
- `has_next_page` (boolean): Whether there are more pages of breakdown rows
- `notice` (string): Recovery hint when results are empty — the account code may not exist or may have no obligations on this axis. Absent when results are present.
- `page_metadata` (object): Pagination metadata
- `results` (array): Breakdown rows for the requested dimension
- `totalCount` (number): Total number of breakdown rows across all pages (when available)

### `usaspending_search_federal_accounts` (~200 tokens)

Search Federal Accounts

List and keyword-search federal accounts by agency identifier or title keyword. Returns account numbers, names, managing agencies, and budgetary resources. Use account_number from results as input to usaspending_get_federal_account for full budget detail. Use usaspending_list_agencies to look up agency_identifier codes (3-digit strings, e.g. "097" for DoD).

Input parameters:

- `agency_identifier` (string): 3-digit agency identifier code (e.g., "097" for Department of Defense). Use usaspending_list_agencies to look up codes.
- `keyword` (string): Filter accounts by name or title keyword (e.g., "defense", "transportation")
- `limit` (integer): Maximum results per page (1–100)
- `page` (integer): Page number (1-based)
- `sort_direction` (string): Sort direction
- `sort_field` (string): Field to sort results by

Output parameters:

- `has_next` (boolean): Whether there are more pages of results
- `notice` (string): Recovery hint when results are empty — echoes applied filters and suggests how to broaden. Absent when results are present.
- `page` (number): Current page number returned
- `page_metadata` (object): Pagination metadata
- `results` (array): Matching federal accounts
- `totalCount` (number): Total number of matching accounts across all pages (when available)

## Diagnostics

Captured diagnostic sections: TLS, DNSSEC, Authorisation, Transports. The full working is on the page: https://verifymcp.io/servers/cyanheads-usaspending-mcp-server/usaspending#diagnostics

## Score history

- 2026-08-03: 67
- 2026-08-02: 67
- 2026-08-01: 66
- 2026-07-31: 66
- 2026-07-30: 64
- 2026-07-29: 63
- 2026-07-28: 63
- 2026-07-27: 63
- 2026-07-26: 62

## Links

- Remote endpoint: https://usaspending.caseyjhand.com/mcp
- Repository: https://github.com/cyanheads/usaspending-mcp-server
- Changelog RSS feed: https://verifymcp.io/servers/cyanheads-usaspending-mcp-server/usaspending/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/cyanheads-usaspending-mcp-server/usaspending/changelog.json
- HTML version of this page: https://verifymcp.io/servers/cyanheads-usaspending-mcp-server/usaspending