Metadata-Version: 2.5
Name: sam-gov-mcp
Version: 1.0.9
Summary: MCP server for SAM.gov entity registration, exclusion, contract opportunity, and contract award data
Project-URL: Homepage, https://1102tools.com
Project-URL: Repository, https://github.com/1102tools/federal-contracting-mcps
Project-URL: Issues, https://github.com/1102tools/federal-contracting-mcps/issues
Author: James Jenrette / 1102tools
License: MIT
Keywords: 1102,FPDS,contract-awards,debarment,exclusions,federal-contracts,mcp,model-context-protocol,procurement,sam.gov
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: filelock>=3.13
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp<3,>=2.0.0
Requires-Dist: platformdirs>=4.0
Description-Content-Type: text/markdown

# sam-gov-mcp

<!-- mcp-name: io.github.1102tools/sam-gov-mcp -->

MCP server for SAM.gov entity registration, exclusion/debarment, contract opportunity, contract award, federal hierarchy, and FFATA subaward data.

Requires a free SAM.gov API key. Standalone MCP use is an advanced, self-supported path; packaged agents are the maintained beginner path.

*Tested and hardened through ten audit rounds including a ~230-call paced live campaign. 1,136 regression tests. v0.4 added 278 tests for Federal Hierarchy + FFATA Subaward endpoints (123 live), catching three silently-ignored Subaward API parameter casings during live audit. Birthplace of the `extra='forbid'` cross-fix applied to all 8 MCPs in the suite. See [testing.md](testing.md) for the full testing record.*

## What it does

Exposes seven SAM.gov REST APIs as 19 MCP tools:

**Entity Management (v3)**
- `lookup_entity_by_uei` - Single UEI lookup with configurable response sections
- `lookup_entity_by_cage` - CAGE code lookup
- `search_entities` - Flexible entity search (NAICS, PSC, business type, state, name, etc.)
- `get_entity_reps_and_certs` - FAR/DFARS reps and certs (must be requested explicitly)
- `get_entity_integrity_info` - FAPIIS proceedings data

**Exclusions (v4)**
- `check_exclusion_by_uei` - Single-UEI debarment check
- `search_exclusions` - Broader exclusion search by name, classification, program, agency, date

**Contract Opportunities (v2)**
- `search_opportunities` - Search contract opportunities with full working filter set
- `get_opportunity_description` - Fetch the HTML description by notice ID

**Contract Awards (v1) -- FPDS replacement**
- `search_contract_awards` - Search contract award records (vendor, agency, NAICS, dates, dollars, set-aside, etc.)
- `lookup_award_by_piid` - Look up all modifications for a single PIID
- `search_deleted_awards` - Search deleted award records for audit trails

**Federal Hierarchy (v1)**
- `search_federal_organizations` - Search the FH for departments, agencies, sub-agencies, offices (filter by FH org id, name, type, status, agency code, CGAC)
- `get_organization_hierarchy` - Walk the children of a federal organization

**Acquisition Subaward Reporting (FFATA subcontracts)**
- `search_acquisition_subawards` - Search FFATA subcontract reports (prime/sub relationships, agency, dates, status)

**Assistance Subaward Reporting (FFATA grant subawards)**
- `search_assistance_subawards` - Search FFATA grant subaward reports (FAIN, prime award key, agency, dates)

**PSC Lookup**
- `lookup_psc_code` - Resolve a PSC code to its full record
- `search_psc_free_text` - Free-text PSC discovery

**Composite workflow**
- `vendor_responsibility_check` - One-shot FAR 9.104-1 check (entity + exclusions in a single tool call)

## Authentication

Requires a SAM.gov API key set via the `SAM_API_KEY` environment variable.

Get a free key at [sam.gov/profile/details](https://sam.gov/profile/details) under "Public API Key."

| Account Type | Daily Limit |
|---|---|
| Non-federal, no SAM role | 10/day |
| Non-federal with SAM role | 1,000/day |
| Federal personal | 1,000/day |
| Federal system account | 10,000/day |

**Important: SAM.gov API keys expire every 90 days.** Regenerate at the same profile page and update your env var. This server returns a clear actionable error on 401/403 with regeneration instructions.

## Installation

### Via uvx (recommended)

```bash
uvx sam-gov-mcp
```

### Via pip

```bash
pip install sam-gov-mcp
```

### From source

```bash
git clone https://github.com/1102tools-dev/federal-contracting-mcps.git
cd federal-contracting-mcps/servers/sam-gov-mcp
pip install -e .
```

## Configuration

MCP is an open standard, and compatible clients can run this server. The maintained [1102tools Agent Setup Guide](https://1102tools.com/downloads/1102tools-agent-setup-guide.pdf) covers packaged agents in Codex and Claude Code, not standalone server configuration. Use the block below as the server definition and adapt its placement to your client.

```json
{
  "mcpServers": {
    "sam-gov": {
      "command": "uvx",
      "args": ["--refresh-package", "sam-gov-mcp", "--from", "sam-gov-mcp", "sam-gov-mcp"],
      "env": {
        "SAM_API_KEY": "SAM-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}
```

The `--refresh-package` flag tells uv to check PyPI for a newer release each time your client launches the server, so fixes arrive automatically; without it, uv keeps serving whatever version it first cached. It adds a moment of network time at startup, so raise your platform's MCP startup timeout if it enforces a short one.

Restart the client and the tools appear.

## Example prompts

Once configured, these examples illustrate the server's advanced standalone use. The maintained [MCP-oriented request library](https://github.com/1102tools-dev/federal-contracting-prompts) contains the broader collection:

- "Run a vendor responsibility check on [UEI] for registration status and exclusions, then pull FAPIIS integrity records separately; the one-pass check does not include those."
- "Pull [COMPANY]'s registration status, socioeconomic categories, and any exclusions. If SAM returns multiple registrations for one UEI, say so and list them before picking one."
- "Get [COMPANY]'s FAR 52.212-3 and DFARS 252.204-7016 answers from their reps and certs (summary mode), and flag anything a contracting officer would want to read in full text."
- "How far back does [COMPANY]'s federal award history actually go? Check contract awards decade by decade, FY1970 forward; volumes thin out before 1980, so read single-digit years as archival traces, not gaps."
- "Find active 8(a)-certified firms (SBA-certified, not self-designated) in [STATE] under NAICS [NAICS]."
- "Search sources sought notices from the last 30 days under NAICS [NAICS], response deadlines sorted soonest first."
- "Show me SDVOSB set-aside solicitations for IT services posted this quarter."
- "Get the full description of notice ID [paste ID] and summarize the SOW."
- "Search exclusions for [NAME]: give me classification (Firm, Individual, Vessel), excluding agency, and whether each record is active."
- "Search contract awards for [COMPANY] in fiscal year 2026, then look up all modifications for the biggest PIID you find."
- "Show me deleted contract award records for Department of Defense this fiscal year."
- "Find the Federal Hierarchy ID for the Department of the Treasury and walk one level of children."
- "Show me FFATA subcontracts on prime PIID [PIID], and total the subaward amounts."
- "Pull all subawards reported under grant FAIN [FAIN]."
- "List the agency-level orgs in CGAC 075 (HHS)."

## Design notes

- **Authentication via env var only.** `SAM_API_KEY` is read from the environment on every call. The key never enters the model's conversation context.
- **90-day expiration awareness.** 401/403 errors are translated into an actionable "regenerate at sam.gov/profile/details" message with full context.
- **API quirks baked in as safety rails.**
  - Entity Management hard cap of size=10 is enforced client-side with a clear error
  - Exclusions uses `size` not `limit` (different from other SAM endpoints)
  - Country codes are validated as 3-character ISO alpha-3 (2-char codes return 0 silently)
  - No `Accept: application/json` header is set (Exclusions returns 406 if present)
  - Bracket/tilde/exclamation characters are preserved in query strings for multi-value params
- **Post-filtering for broken parameters.** The Opportunities API silently ignores `deptname` and `subtier` filters. `search_opportunities` exposes an `agency_keyword` parameter that post-filters results by matching `fullParentPathName` substring.
- **includeSections defaults.** Entity lookups default to `entityRegistration,coreData`. Always include `entityRegistration` alongside any other section or the response has no identification. `repsAndCerts` and `integrityInformation` require explicit tool calls (`get_entity_reps_and_certs`, `get_entity_integrity_info`) because even `includeSections=All` doesn't include them.
- **Contract Awards response normalization.** The Contract Awards API returns different JSON wrapper shapes for populated vs. empty results. All tools normalize this to a consistent `{"awardSummary": [...], "totalRecords": int}` shape. Error responses are plain text (not JSON), detected and raised as actionable errors.
- **Contract Awards pagination.** Uses `limit`/`offset` (NOT `page`/`size` like Entity Management). Max limit is 100. Dates must be MM/dd/yyyy format with bracket ranges `[MM/dd/yyyy,MM/dd/yyyy]`.
- **Composite workflow.** `vendor_responsibility_check` collapses a typical FAR 9.104-1 check (entity registration + exclusion lookup) into one tool call, returning a structured flags list for downstream reasoning.
- **Federal Hierarchy quirks baked in.**
  - Lowercase `totalrecords` and `orglist` keys (rest of SAM.gov uses camelCase); normalizer preserves both
  - Default response is ACTIVE-only; passing `status=ACTIVE` is a no-op vs. the unfiltered call. Pass `INACTIVE` to expand to retired orgs
  - Real `fhorgtype` values look like `Department/Ind. Agency`, but the API also accepts shorthand (DEPARTMENT, AGENCY) with case-insensitive matching
- **Subaward Reporting quirks baked in.**
  - Dates use ISO `yyyy-MM-dd` (NOT `MM/dd/yyyy` like Contract Awards). Mixing them raises a clear pre-network validation error
  - Pagination uses `pageNumber`/`pageSize` (NOT `page`/`size` or `limit`/`offset`)
  - Live audit (April 2026) found three documented parameter casings are silently ignored: `PIID` is dropped (use lowercase `piid`), `referencedIdvPIID` is dropped (use `referencedIDVPIID`), and `referencedIDVAgencyID` is dropped (use `referencedIDVAgencyId`). Wire-level names are now correct in the server

## Part of

[federal-contracting-mcps](https://github.com/1102tools-dev/federal-contracting-mcps): monorepo of 9 MCP servers for federal contracting data. Companion to [federal-contracting-skills](https://github.com/1102tools-dev/federal-contracting-skills).

## Request pacing

Every request, including composite-tool subrequests, uses a provisional
3-second cross-process anti-burst interval by default. The local gate uses a
one-way key fingerprint and never stores the raw SAM key. It does not create
additional daily quota or coordinate the same key on another computer.
Override with `FEDERAL_API_MIN_INTERVAL_SECONDS`, use `0` to deliberately
disable it, and use `FEDERAL_API_PACING_DIR` to relocate local pacing state.

## License

MIT
