---
name: iblai-connect-usaspending
description: "Read USAspending.gov data through the USAspending API (v2) and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with USAspending.gov data, or to set up a USAspending.gov MCP connection on ibl.ai."
metadata:
  kind: guide
---

# USAspending.gov connector for AI agents

> A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/usaspending — not part of the iblai/vibe repository. Checked against the Bureau of the Fiscal Service's documentation on October 20, 2026; test it against your own USAspending.gov setup before you rely on it.

USAspending.gov is the official source of U.S. federal spending data under FFATA and the DATA Act: contracts, grants, loans and other awards, recipients, agencies, federal accounts and subawards.

## Auth & conventions

- **API:** USAspending API (v2) (REST). Award search and counts with complex filters, award detail and funding, recipient profiles, agency overviews, spending by category and geography, autocomplete lookups, and bulk CSV downloads.
- **Base URL:** https://api.usaspending.gov/api/v2/
- **Access:** Public, self-serve. The documentation states endpoints do not currently require any authorization. No key or registration is needed.
- **Auth:** None required. Endpoints are open. Single records with a known ID use GET; filtered searches use POST with a JSON body.
- **Limits:** No rate limits are documented. Award search returns 10 results by default and pages with page; page_metadata.hasNext signals more results.
- Keep USAspending.gov credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file.
- Destructive or outward-facing calls are marked **Confirm with the user first** — do.

## Reads

- **Award search** — POST /api/v2/search/spending_by_award/ with filters; award_type_codes is required. Paged with page and limit; response has page_metadata.hasNext.
- **Award detail** — GET /api/v2/awards/{award_id}/ and /api/v2/awards/funding for federal account funding.
- **Recipients** — /api/v2/recipient/ lists recipients; /api/v2/recipient/{hash}/ returns a profile.
- **Agencies** — GET /api/v2/agency/{toptier_code}/ and /api/v2/references/toptier_agencies/.
- **Spending breakdowns** — POST /api/v2/search/spending_by_category/ and /spending_by_geography/.
- **Bulk download** — POST /api/v2/bulk_download/awards/ queues a CSV; check /api/v2/bulk_download/status/.

## Writes

- None. This skill only reads USAspending.gov data.

## Expose it to an ibl.ai agent (MCP)

the Bureau of the Fiscal Service did not publish an MCP server of its own when this skill was checked. Host a small MCP server that wraps the calls above, then register it below.

First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`):

```bash
npx skills add iblai/vibe --all
# then, in your coding agent:
/iblai-api-login
```

Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`.

1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`.
   - For an API key or service credential use `auth_type=token` with `auth_scope=platform` for one key across the organization, or scope it to a single agent for one key per agent.
2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back.
3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged.

Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill.

## Example prompts

- "Total federal grant dollars awarded to Ohio recipients in fiscal year 2025"
- "List the 20 largest DoD contracts awarded last quarter"
- "Show all awards to recipient UEI ABC123DEF456 since 2022"
- "Break down NASA obligations by state for this fiscal year"

## Guardrails

- Public data released under FFATA and the DATA Act. Recipient names and locations are published; Dun & Bradstreet-derived fields carry a permissible-use limitation.
- Request the narrowest USAspending.gov scopes or role the task needs, and prefer a read-only credential for agents that only answer questions.
- Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request.
- Before any write, show the user exactly what will change and wait for a yes.
- Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop.

## References

- USAspending API: https://api.usaspending.gov/
- API endpoints: https://api.usaspending.gov/docs/endpoints
- Spending by Award contract: https://github.com/fedspendingtransparency/usaspending-api/blob/master/usaspending_api/api_contracts/contracts/v2/search/spending_by_award.md
- This connector on ibl.ai: https://ibl.ai/developer/connectors/usaspending
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections