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 descriptions
• recipientName - Contractor/recipient name
• agencyName - 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 activity
• activityEndDate - End date (YYYY-MM-DD) for transaction activity
• minAmount / maxAmount - Award amount range
• state - State code for place of performance
• awardTypeCodes - 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 date
• awardEndDate - 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 - The generated_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 string
• limit - 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 - The generated_unique_award_id (internalId) of the parent IDV
• limit - 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_awards
• activityStartDate / activityEndDate - Date range (defaults to last year)
• minAmount - Minimum award size to analyze
• limit - 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.