---
name: iblai-connect-sam-gov
description: "Read SAM.gov data through the SAM.gov Entity Management API, Get Opportunities Public API, Contract Awards API and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with SAM.gov data, or to set up a SAM.gov MCP connection on ibl.ai."
metadata:
  kind: guide
---

# SAM.gov connector for AI agents

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

SAM.gov is the federal System for Award Management. It holds entity registrations (UEI, NAICS, business types), contract opportunities, FPDS contract awards and exclusions.

## Auth & conventions

- **API:** SAM.gov Entity Management API, Get Opportunities Public API, Contract Awards API (REST). Search entity registrations by UEI, name, NAICS and more; search contract opportunities by posted date with notice details, set-asides and contacts; search FPDS contract awards. Async extracts return large CSV or JSON files.
- **Base URL:** https://api.sam.gov/ (e.g. /entity-information/v4/entities, /opportunities/v2/search, /contract-awards/v1/search)
- **Access:** Public, self-serve. Any registered SAM.gov user can generate a personal Public API Key on their Account Details page. Organizations can request a system account (IP allowlist, roles) for higher limits and FOUO or sensitive data.
- **Auth:** API key (api_key query parameter or header); System account with Basic Auth (sensitive data). Pass the SAM.gov API key as api_key. Sensitive entity data (banking, TIN) requires a system account with the Read Sensitive role, sent via POST with Basic Auth credentials.
- **Limits:** Daily request limits by key: 10 for non-federal users with no role; 1,000 for federal or role-holding users and non-federal system accounts; 10,000 for federal system accounts. Entity search returns at most the first 10,000 records.
- Keep SAM.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

- **Entity registrations** — GET /entity-information/v4/entities: UEI, legal name, addresses, NAICS, business types; 10 records per page.
- **Contract opportunities** — GET /opportunities/v2/search with postedFrom and postedTo (MM/dd/yyyy), limit up to 1,000, offset.
- **Contract awards (FPDS)** — GET /contract-awards/v1/search for delivery orders, BPAs, GWACs and other contract awards.
- **Entity extracts** — Asynchronous CSV or JSON extract via the format parameter, up to 1,000,000 records.

## Writes

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

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

GSA 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

- "Find active solicitations for NAICS 541512 posted in the last 14 days"
- "Look up the SAM registration and expiration date for UEI ABC123DEF456"
- "List small-business set-aside opportunities from the VA this month"
- "Show FPDS contract awards to our company in fiscal year 2026"

## Guardrails

- Most data is public. Entity data marked FOUO is CUI (contacts, hierarchy) and Sensitive is CUI (banking, SSN/TIN/EIN), gated by account roles.
- Request the narrowest SAM.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

- SAM.gov Entity Management API: https://open.gsa.gov/api/entity-api/
- Get Opportunities Public API: https://open.gsa.gov/api/get-opportunities-public-api/
- SAM.gov Contract Awards API: https://open.gsa.gov/api/contract-awards/
- This connector on ibl.ai: https://ibl.ai/developer/connectors/sam-gov
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections