USASpending MCP Server
A Model Context Protocol (MCP) server for researching federal contract awards and analyzing the competitive landscape using the USASpending.gov API. Built with Next.js and designed for AI agents to research government contracts, identify incumbents, and analyze market opportunities.
Features
This MCP server provides 8 specialized tools for federal contracting research:
- search_awards - Search for federal contract awards with filters for agencies, NAICS/PSC codes, keywords, dates, and more
- search_new_awards - Find newly signed contracts by their award date (action date), excluding modifications
- get_award_details - Get comprehensive details about a specific award
- search_recipients - Search for contractors/recipients with autocomplete
- get_recipient_details - Get detailed information about a specific recipient
- search_idv_awards - Find task orders under Indefinite Delivery Vehicles (IDVs)
- get_spending_over_time - Analyze spending trends over time (by fiscal year, quarter, or month)
- analyze_competition - Analyze competitive landscape showing market shares and top recipients
Architecture
The codebase is organized into a modular structure for maintainability:
src/
├── builders/
│ ├── filter-builder.ts # Centralized filter building logic
│ └── field-mapper.ts # Field name mappings and transformers
├── clients/
│ └── usaspending.ts # API client with retry logic
├── tools/
│ ├── search-awards.ts
│ ├── search-new-awards.ts
│ ├── get-award-details.ts
│ ├── search-recipients.ts
│ ├── get-recipient-details.ts
│ ├── search-idv-awards.ts
│ ├── get-spending-over-time.ts
│ ├── analyze-competition.ts
│ └── index.ts # Tool registration
└── types/
├── award.ts
├── recipient.ts
└── tool-params.ts
Key Design Features
- Centralized Filter Builder: Shared logic for building API filters across tools
- Field Mapper: Manages field name differences between API endpoints (verified against actual API)
- Type Safety: Comprehensive TypeScript types for API requests/responses
- Modular Tools: Each tool in its own file for easy maintenance
- Error Handling: Robust retry logic with exponential backoff for rate limiting
Installation
npm install
Configuration
The server requires no API keys - the USASpending.gov API is public. For production deployment on Vercel, you can optionally configure Redis for SSE transport:
KV_REST_API_URL=your-redis-url
Usage
Development
npm run dev
The MCP server will be available at http://localhost:3000/mcp
Building
npm run build
npm start
Deployment on Vercel
Deploy with:
npx vercel --prod
The repository is configured with:
- 300 second timeout for complex queries
- 1024MB memory allocation
- SSE transport support (requires Redis)
See vercel.json for configuration details.
Tool Reference
search_awards
Search for federal contract awards with transaction activity during a date range.
Important: Date filtering searches for awards that had ANY transaction activity (modifications, obligations, payments) during the date range - this includes both new awards and existing awards with recent modifications. For finding only newly signed awards, use search_new_awards instead.
Parameters:
keywords- Keywords to search in award descriptionsrecipientName- Contractor/recipient nameagencyName- Awarding agency name (e.g., "Department of Veterans Affairs")naicsCodes- Array of NAICS codes (e.g., ["541511"] for Custom Computer Programming)pscCodes- Product Service Codes (e.g., ["D307"] for IT/Telecom)activityStartDate- Start date (YYYY-MM-DD) for transaction activityactivityEndDate- End date (YYYY-MM-DD) for transaction activityminAmount/maxAmount- Award amount rangestate- State code for place of performanceawardTypeCodes- Award type codes (default: ['A','B','C','D'] for contracts)setAsideTypes- Set aside types (e.g., 'SDVOSBC', '8A', 'WOSB')extentCompeted- Competition codes (e.g., 'A' for full and open)contractPricingTypes- Pricing types (e.g., 'FFPF', 'TM', 'CPFF')limit- Number of results (max 100, default 10)
search_new_awards
Search for newly awarded contracts by their award date (Action Date). Returns only BASE awards (Modification Number = 0), not modifications to existing awards.
Use this when you need to find contracts that were actually signed/awarded during a specific date range (e.g., "awards signed yesterday", "new contracts this week").
Parameters:
awardStartDate- Start date (YYYY-MM-DD) - earliest award signing dateawardEndDate- End date (YYYY-MM-DD) - defaults to awardStartDate if not provided- All other parameters same as
search_awards
get_award_details
Get comprehensive details about a specific award including description, recipient, transactions, sub-awards, and more.
Parameters:
awardId- Thegenerated_unique_award_id(internalId) from search results
Note: Use the internalId field from search results, NOT the human-readable Award ID (PIID).
search_recipients
Search for contractors/recipients using autocomplete.
Parameters:
search- Search query stringlimit- Number of results (default 10)
get_recipient_details
Get detailed information about a specific recipient including total awards, transaction history, and more.
Parameters:
recipientHash- The recipient hash ID from search results
search_idv_awards
Find task orders and child awards under an Indefinite Delivery Vehicle (IDV). Useful for understanding who holds a contract vehicle and who is getting task orders.
Parameters:
awardId- Thegenerated_unique_award_id(internalId) of the parent IDVlimit- Number of results (max 100, default 25)
Background: IDVs are contract vehicles like GWACs, GSA Schedules, and BPAs that spawn individual task orders.
get_spending_over_time
Analyze spending trends over time for transaction activity. Returns time-series data grouped by fiscal year, quarter, or month.
Parameters:
- All filter parameters from
search_awards group- How to group data: 'fiscal_year', 'quarter', or 'month' (default: 'fiscal_year')
Note: Analyzes transaction activity (when money was obligated), not original award dates.
analyze_competition
Analyze the competitive landscape based on transaction activity. Shows who's winning awards/modifications, market shares, and spending patterns.
Parameters:
keywords,agencyName,naicsCodes,pscCodes- Same as search_awardsactivityStartDate/activityEndDate- Date range (defaults to last year)minAmount- Minimum award size to analyzelimit- Number of top recipients to show (default 20)
Note: Analyzes transaction activity, which includes both new awards and modifications to existing awards.
Understanding Date Fields
The USASpending API has different date concepts that are important to understand:
- Action Date - When a transaction was executed (used by
search_new_awards) - Activity Period - The time period filter for
search_awards(when any financial activity occurred) - Period of Performance - Start/End dates when the contract work is performed (NOT award dates)
API Client Features
The USASpendingClient includes:
- Rate Limiting Protection: Automatic throttling (100ms between requests)
- Retry Logic: Exponential backoff for 429 rate limit errors (up to 2 retries)
- Error Handling: Detailed logging and error messages
- Timeouts: 90 second timeout for complex queries
- Request Delay: Configurable delay between requests to avoid rate limits
Verified Field Names
The transaction endpoint (search_new_awards) uses different field names than the award endpoint. All field names have been verified against the actual API:
Transaction Fields:
- "Award ID", "Recipient Name", "Action Date", "Transaction Amount"
- "Awarding Agency", "Awarding Sub Agency"
- "Transaction Description", "Mod" (modification number)
- "naics_code", "naics_description", "product_or_service_code", "product_or_service_description"
Development
Type Checking
npm run type-check
Formatting
npm run format
Linting
npm run lint:fix
Resources
- USASpending API Documentation
- MCP TypeScript SDK
- Vercel MCP Adapter (mcp-handler)
- Model Context Protocol Specification
Notes
- The USASpending API can be slow for complex queries (90+ seconds for large result sets)
- No API key required - the API is public
- The server uses SSE transport when Redis is configured (required for Vercel)
- Fluid compute is recommended for efficient execution on Vercel
License
This project is maintained by Agile Six Applications.